misc.go

Documentation: github.com/google/go-github/v47/github

     1  // Copyright 2014 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  package github
     7  
     8  import (
     9  	"bytes"
    10  	"context"
    11  	"fmt"
    12  	"net/url"
    13  )
    14  
    15  // MarkdownOptions specifies optional parameters to the Markdown method.
    16  type MarkdownOptions struct {
    17  	// Mode identifies the rendering mode. Possible values are:
    18  	//   markdown - render a document as plain Markdown, just like
    19  	//   README files are rendered.
    20  	//
    21  	//   gfm - to render a document as user-content, e.g. like user
    22  	//   comments or issues are rendered. In GFM mode, hard line breaks are
    23  	//   always taken into account, and issue and user mentions are linked
    24  	//   accordingly.
    25  	//
    26  	// Default is "markdown".
    27  	Mode string
    28  
    29  	// Context identifies the repository context. Only taken into account
    30  	// when rendering as "gfm".
    31  	Context string
    32  }
    33  
    34  type markdownRequest struct {
    35  	Text    *string `json:"text,omitempty"`
    36  	Mode    *string `json:"mode,omitempty"`
    37  	Context *string `json:"context,omitempty"`
    38  }
    39  
    40  // Markdown renders an arbitrary Markdown document.
    41  //
    42  // GitHub API docs: https://docs.github.com/en/rest/markdown/
    43  func (c *Client) Markdown(ctx context.Context, text string, opts *MarkdownOptions) (string, *Response, error) {
    44  	request := &markdownRequest{Text: String(text)}
    45  	if opts != nil {
    46  		if opts.Mode != "" {
    47  			request.Mode = String(opts.Mode)
    48  		}
    49  		if opts.Context != "" {
    50  			request.Context = String(opts.Context)
    51  		}
    52  	}
    53  
    54  	req, err := c.NewRequest("POST", "markdown", request)
    55  	if err != nil {
    56  		return "", nil, err
    57  	}
    58  
    59  	buf := new(bytes.Buffer)
    60  	resp, err := c.Do(ctx, req, buf)
    61  	if err != nil {
    62  		return "", resp, err
    63  	}
    64  
    65  	return buf.String(), resp, nil
    66  }
    67  
    68  // ListEmojis returns the emojis available to use on GitHub.
    69  //
    70  // GitHub API docs: https://docs.github.com/en/rest/emojis/
    71  func (c *Client) ListEmojis(ctx context.Context) (map[string]string, *Response, error) {
    72  	req, err := c.NewRequest("GET", "emojis", nil)
    73  	if err != nil {
    74  		return nil, nil, err
    75  	}
    76  
    77  	var emoji map[string]string
    78  	resp, err := c.Do(ctx, req, &emoji)
    79  	if err != nil {
    80  		return nil, resp, err
    81  	}
    82  
    83  	return emoji, resp, nil
    84  }
    85  
    86  // CodeOfConduct represents a code of conduct.
    87  type CodeOfConduct struct {
    88  	Name *string `json:"name,omitempty"`
    89  	Key  *string `json:"key,omitempty"`
    90  	URL  *string `json:"url,omitempty"`
    91  	Body *string `json:"body,omitempty"`
    92  }
    93  
    94  func (c *CodeOfConduct) String() string {
    95  	return Stringify(c)
    96  }
    97  
    98  // ListCodesOfConduct returns all codes of conduct.
    99  //
   100  // GitHub API docs: https://docs.github.com/en/rest/codes_of_conduct/#list-all-codes-of-conduct
   101  func (c *Client) ListCodesOfConduct(ctx context.Context) ([]*CodeOfConduct, *Response, error) {
   102  	req, err := c.NewRequest("GET", "codes_of_conduct", nil)
   103  	if err != nil {
   104  		return nil, nil, err
   105  	}
   106  
   107  	// TODO: remove custom Accept header when this API fully launches.
   108  	req.Header.Set("Accept", mediaTypeCodesOfConductPreview)
   109  
   110  	var cs []*CodeOfConduct
   111  	resp, err := c.Do(ctx, req, &cs)
   112  	if err != nil {
   113  		return nil, resp, err
   114  	}
   115  
   116  	return cs, resp, nil
   117  }
   118  
   119  // GetCodeOfConduct returns an individual code of conduct.
   120  //
   121  // https://docs.github.com/en/rest/codes_of_conduct/#get-an-individual-code-of-conduct
   122  func (c *Client) GetCodeOfConduct(ctx context.Context, key string) (*CodeOfConduct, *Response, error) {
   123  	u := fmt.Sprintf("codes_of_conduct/%s", key)
   124  	req, err := c.NewRequest("GET", u, nil)
   125  	if err != nil {
   126  		return nil, nil, err
   127  	}
   128  
   129  	// TODO: remove custom Accept header when this API fully launches.
   130  	req.Header.Set("Accept", mediaTypeCodesOfConductPreview)
   131  
   132  	coc := new(CodeOfConduct)
   133  	resp, err := c.Do(ctx, req, coc)
   134  	if err != nil {
   135  		return nil, resp, err
   136  	}
   137  
   138  	return coc, resp, nil
   139  }
   140  
   141  // APIMeta represents metadata about the GitHub API.
   142  type APIMeta struct {
   143  	// An Array of IP addresses in CIDR format specifying the addresses
   144  	// that incoming service hooks will originate from on GitHub.com.
   145  	Hooks []string `json:"hooks,omitempty"`
   146  
   147  	// An Array of IP addresses in CIDR format specifying the Git servers
   148  	// for GitHub.com.
   149  	Git []string `json:"git,omitempty"`
   150  
   151  	// Whether authentication with username and password is supported.
   152  	// (GitHub Enterprise instances using CAS or OAuth for authentication
   153  	// will return false. Features like Basic Authentication with a
   154  	// username and password, sudo mode, and two-factor authentication are
   155  	// not supported on these servers.)
   156  	VerifiablePasswordAuthentication *bool `json:"verifiable_password_authentication,omitempty"`
   157  
   158  	// An array of IP addresses in CIDR format specifying the addresses
   159  	// which serve GitHub Pages websites.
   160  	Pages []string `json:"pages,omitempty"`
   161  
   162  	// An Array of IP addresses specifying the addresses that source imports
   163  	// will originate from on GitHub.com.
   164  	Importer []string `json:"importer,omitempty"`
   165  
   166  	// An array of IP addresses in CIDR format specifying the IP addresses
   167  	// GitHub Actions will originate from.
   168  	Actions []string `json:"actions,omitempty"`
   169  
   170  	// An array of IP addresses in CIDR format specifying the IP addresses
   171  	// Dependabot will originate from.
   172  	Dependabot []string `json:"dependabot,omitempty"`
   173  
   174  	// A map of algorithms to SSH key fingerprints.
   175  	SSHKeyFingerprints map[string]string `json:"ssh_key_fingerprints,omitempty"`
   176  
   177  	// An array of SSH keys.
   178  	SSHKeys []string `json:"ssh_keys,omitempty"`
   179  
   180  	// An array of IP addresses in CIDR format specifying the addresses
   181  	// which serve GitHub websites.
   182  	Web []string `json:"web,omitempty"`
   183  
   184  	// An array of IP addresses in CIDR format specifying the addresses
   185  	// which serve GitHub APIs.
   186  	API []string `json:"api,omitempty"`
   187  }
   188  
   189  // APIMeta returns information about GitHub.com, the service. Or, if you access
   190  // this endpoint on your organization’s GitHub Enterprise installation, this
   191  // endpoint provides information about that installation.
   192  //
   193  // GitHub API docs: https://docs.github.com/en/rest/meta#get-github-meta-information
   194  func (c *Client) APIMeta(ctx context.Context) (*APIMeta, *Response, error) {
   195  	req, err := c.NewRequest("GET", "meta", nil)
   196  	if err != nil {
   197  		return nil, nil, err
   198  	}
   199  
   200  	meta := new(APIMeta)
   201  	resp, err := c.Do(ctx, req, meta)
   202  	if err != nil {
   203  		return nil, resp, err
   204  	}
   205  
   206  	return meta, resp, nil
   207  }
   208  
   209  // Octocat returns an ASCII art octocat with the specified message in a speech
   210  // bubble. If message is empty, a random zen phrase is used.
   211  func (c *Client) Octocat(ctx context.Context, message string) (string, *Response, error) {
   212  	u := "octocat"
   213  	if message != "" {
   214  		u = fmt.Sprintf("%s?s=%s", u, url.QueryEscape(message))
   215  	}
   216  
   217  	req, err := c.NewRequest("GET", u, nil)
   218  	if err != nil {
   219  		return "", nil, err
   220  	}
   221  
   222  	buf := new(bytes.Buffer)
   223  	resp, err := c.Do(ctx, req, buf)
   224  	if err != nil {
   225  		return "", resp, err
   226  	}
   227  
   228  	return buf.String(), resp, nil
   229  }
   230  
   231  // Zen returns a random line from The Zen of GitHub.
   232  //
   233  // see also: http://warpspire.com/posts/taste/
   234  func (c *Client) Zen(ctx context.Context) (string, *Response, error) {
   235  	req, err := c.NewRequest("GET", "zen", nil)
   236  	if err != nil {
   237  		return "", nil, err
   238  	}
   239  
   240  	buf := new(bytes.Buffer)
   241  	resp, err := c.Do(ctx, req, buf)
   242  	if err != nil {
   243  		return "", resp, err
   244  	}
   245  
   246  	return buf.String(), resp, nil
   247  }
   248  
   249  // ServiceHook represents a hook that has configuration settings, a list of
   250  // available events, and default events.
   251  type ServiceHook struct {
   252  	Name            *string    `json:"name,omitempty"`
   253  	Events          []string   `json:"events,omitempty"`
   254  	SupportedEvents []string   `json:"supported_events,omitempty"`
   255  	Schema          [][]string `json:"schema,omitempty"`
   256  }
   257  
   258  func (s *ServiceHook) String() string {
   259  	return Stringify(s)
   260  }
   261  
   262  // ListServiceHooks lists all of the available service hooks.
   263  //
   264  // GitHub API docs: https://developer.github.com/webhooks/#services
   265  func (c *Client) ListServiceHooks(ctx context.Context) ([]*ServiceHook, *Response, error) {
   266  	u := "hooks"
   267  	req, err := c.NewRequest("GET", u, nil)
   268  	if err != nil {
   269  		return nil, nil, err
   270  	}
   271  
   272  	var hooks []*ServiceHook
   273  	resp, err := c.Do(ctx, req, &hooks)
   274  	if err != nil {
   275  		return nil, resp, err
   276  	}
   277  
   278  	return hooks, resp, nil
   279  }
   280
View as plain text