geasty/dist/index.d.ts

Simple and easy to use Gist API client

import "ofetch";

//#region src/types.d.ts
interface PaginationOptions {
  /**
   * The page number of the results to fetch.
   *
   * @default 1
   */
  page?: number;
  /**
   * The number of results per page (max 100).
   *
   * @default 30
   */
  per_page?: number;
}
interface GeastyOptions {
  /**
   * Fine-grained personal access tokens
   *
   * @see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token
   */
  access_token?: string;
}
interface CreateAGistOptions {
  /**
   * Description of the gist
   */
  description?: string;
  /**
   * Flag indicating whether the gist is public
   */
  public?: boolean;
  /**
   * Names and content for the files that make up the gist
   *
   * @example
   * ```ts
   * {
   *   'test.txt': {
   *     content: 'Hello World!'
   *   }
   * }
   * ```
   */
  files: {
    /**
     * A user-defined key to represent an item in files.
     */
    [key: string]: {
      /**
       * The new content of the file.
       */
      content: string;
    };
  };
}
interface UpdateAGistOptions {
  /**
   * The unique identifier of the gist.
   */
  gistId: string;
  /**
   * The description of the gist.
   */
  description?: string;
  /**
   * The gist files to be updated, renamed, or deleted. Each key must match the current filename (including extension) of the targeted gist file. For example: hello.py.
   *
   * To delete a file, set the whole file to null. For example: hello.py : null. The file will also be deleted if the specified object does not contain at least one of content or filename.
   */
  files?: {
    /**
     * A user-defined key to represent an item in files.
     */
    [key: string]: {
      /**
       * The new content of the file.
       */
      content?: string;
      /**
       * The new filename for the file.
       */
      filename?: string | null;
    };
  };
}
interface GetGistsOptions extends PaginationOptions {
  /**
   * Only show results that were last updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
   *
   * @see https://en.wikipedia.org/wiki/ISO_8601
   */
  since?: string;
}
interface GetGistForUserOptions extends GetGistsOptions {
  /**
   * The handle for the GitHub user account.
   */
  username: string;
}
interface GetGistForksOrCommitsOptions extends PaginationOptions {
  /**
   * The unique identifier of the gist.
   */
  gistId: string;
}
interface GistConstructorOptions {
  id: string;
  node_id: string;
  description?: string;
  public: boolean;
  created_at: string;
  updated_at: string;
  files: GistFile[];
  owner: GistUser;
  comments: number;
  comments_enabled: boolean;
}
declare class Gist {
  id: string;
  node_id: string;
  description?: string;
  public: boolean;
  created_at: string;
  updated_at: string;
  files: GistFile[];
  owner: GistUser;
  comments: number;
  comments_enabled: boolean;
  constructor(options: GistConstructorOptions);
}
interface GistFileConstructorOptions {
  filename: string;
  type?: string;
  raw_url?: string;
  size?: number;
  language?: string;
  encoding?: 'base64' | 'utf-8';
  content?: string;
  truncated?: boolean;
}
declare class GistFile {
  filename: string;
  type?: string;
  raw_url?: string;
  size?: number;
  language?: string;
  encoding?: 'base64' | 'utf-8';
  content?: string;
  truncated?: boolean;
  constructor(options: GistFileConstructorOptions);
}
interface GistUserConstructorOptions {
  id: number;
  node_id: string;
  login: string;
  name?: string;
  email?: string;
  url: string;
  type: string;
  site_admin: boolean;
}
declare class GistUser {
  id: number;
  login: string;
  node_id: string;
  name?: string;
  email?: string;
  url: string;
  type: string;
  site_admin: boolean;
  constructor(options: GistUserConstructorOptions);
}
interface GistCommitConstructorOptions {
  url: string;
  version: string;
  user?: GistUser;
  change_status: {
    total?: number;
    additions?: number;
    deletions?: number;
  };
  committed_at: string;
}
declare class GistCommit {
  url: string;
  version: string;
  committed_at: string;
  user?: GistUser;
  change_status: {
    total?: number;
    additions?: number;
    deletions?: number;
  };
  constructor(options: GistCommitConstructorOptions);
}
//#endregion
//#region src/utils.d.ts
type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
//#endregion
//#region src/geasty.d.ts
declare class Geasty {
  /**
   * Access token for gist api authentication
   *
   * @private
   */
  private _accessToken?;
  /**
   * Request instance
   *
   * @private
   */
  private _req;
  /**
   * @param options - Geasty options
   *
   * @example
   * ```ts
   * const geasty = new Geast({
   *   access_token: 'your_access_token_created_by_github'
   * })
   * ```
   */
  constructor(options?: GeastyOptions);
  /**
   * Allows you to add a new gist with one or more files.
   *
   * @param options - Options for creating a gist
   * @returns The created gist
   *
   * @example
   * ```ts
   * creaetAGist({
   *   description: 'Example Gist',
   *   public: true,
   *   files: {'test.txt': {content: 'Hello World!'}},
   * })
   * ```
   */
  createAGist(options: CreateAGistOptions): Promise<Gist>;
  /**
   * Delete a gist.
   * The fine-grained token must have the following permission set:
   *   - "Gists" user permissions (write)
   *
   * @param gistId - The unique identifier of the gist.
   *
   * @example
   * ```ts
   * deleteAGist('gist_id')
   * ```
   */
  deleteAGist(gistId: string): Promise<void>;
  /**
   * Allows you to update a gist's description and to update, delete, or rename gist files. Files from the previous version of the gist that aren't explicitly changed during an edit are unchanged.
   * The fine-grained token must have the following permission set:
   *   - "Gists" user permissions (write)
   *
   * @param options - Options for updating a gist
   * @returns Updated gist
   *
   * @example
   * ```ts
   * updateAGist({
   *   gistId: 'gist_id',
   *   description: 'Updated Description',
   *   files: {'test.txt': {content: 'Hello Geasty!'}},
   * })
   * ```
   */
  updateAGist(options: WithRequired<UpdateAGistOptions, 'description'> | WithRequired<UpdateAGistOptions, 'files'>): Promise<Gist>;
  /**
   * Lists the authenticated user's gists or if called anonymously, this returns all public gists.
   *
   * @param options - Options for getting gists
   * @returns List of gists
   *
   * @example
   * ```ts
   * getAllGists({
   *   since: '2023-01-01T00:00:00Z',
   *   page: 1,
   *   per_page: 10,
   * })
   * ```
   */
  getAllGists(options?: GetGistsOptions): Promise<Gist[]>;
  /**
   * Gets a specified gist.
   *
   * @param gistId - The unique identifier of the gist.
   * @returns Gist that matches the gist ID
   *
   * @example
   * ```ts
   * getAGist('gist_id')
   * ```
   */
  getAGist(gistId: string): Promise<Gist>;
  /**
   * Lists public gists for the specified user.
   *
   * @param options - Options for getting gists for a user
   * @returns List of public gists for the specified user
   *
   * @example
   * ```ts
   * getGistsForUser({
   *   username: 'github_username',
   *   since: '2023-01-01T00:00:00Z',
   *   page: 1,
   *   per_page: 10,
   * })
   * ```
   */
  getGistsForUser(options: GetGistForUserOptions): Promise<Gist[]>;
  /**
   * Gets a specified gist revision.
   *
   * @param gistId - The unique identifier of the gist
   * @param sha - The sha of the gist revision
   * @returns Gist revision that matches the gist ID and sha
   *
   * @example
   * ```ts
   * getAGistRevision('gist_id', 'sha')
   * ```
   */
  getAGistRevision(gistId: string, sha: string): Promise<Gist[]>;
  /**
   * List public gists sorted by most recently updated to least recently updated.
   *
   * @param options - Options for getting public gists
   * @returns List of gists
   *
   * @example
   * ```ts
   * getPublicGists({
   *   since: '2023-01-01T00:00:00Z',
   *   page: 1,
   *   per_page: 10,
   * })
   * ```
   */
  getPublicGists(options?: GetGistsOptions): Promise<Gist[]>;
  /**
   * List the authenticated user's starred gists.
   *
   * @param options - Options for getting starred gists
   * @returns List of starred gists
   *
   * @example
   * ```ts
   * getStarredGists({
   *   since: '2023-01-01T00:00:00Z',
   *   page: 1,
   *   per_page: 10,
   * })
   * ```
   */
  getStarredGists(options?: GetGistsOptions): Promise<Gist[]>;
  /**
   * List gist forks.
   *
   * @param options - Options for getting gist forks
   * @returns List of gist forks
   *
   * @example
   * ```ts
   * getGistForks({
   *   gistId: 'gist_id',
   *   page: 1,
   *   per_page: 10,
   * })
   * ```
   */
  getGistForks(options: GetGistForksOrCommitsOptions): Promise<Gist[]>;
  /**
   * List gist commits.
   *
   * @param options - Options for getting gist commits
   * @returns List of gist commits
   *
   * @example
   * ```ts
   * getGistCommits({
   *   gistId: 'gist_id',
   *   page: 1,
   *   per_page: 10,
   * })
   * ```
   */
  getGistCommits(options: GetGistForksOrCommitsOptions): Promise<GistCommit[]>;
  /**
   * Check if a gist is starred.
   *
   * @param gistId - The unique identifier of the gist.
   * @returns Boolean indicating whether the gist is starred
   *
   * @example
   * ```ts
   * isGistStarred('gist_id')
   * ```
   */
  isGistStarred(gistId: string): Promise<boolean>;
  /**
   * Star a gist.
   * The fine-grained token must have the following permission set:
   *   - "Gists" user permissions (write)
   *
   * @param gistId - The unique identifier of the gist.
   *
   * @example
   * ```ts
   * starAGist('gist_id')
   * ```
   */
  starAGist(gistId: string): Promise<void>;
  /**
   * Unstar a gist.
   * The fine-grained token must have the following permission set:
   *   - "Gists" user permissions (write)
   *
   * @param gistId - The unique identifier of the gist.
   *
   * @example
   * ```ts
   * unstarAGist('gist_id')
   * ```
   */
  unstarAGist(gistId: string): Promise<void>;
  /**
   * Fork a gist.
   * The fine-grained token must have the following permission set:
   *   - "Gists" user permissions (write)
   *
   * @param gistId - The unique identifier of the gist.
   *
   * @example
   * ```ts
   * forkAGist('gist_id')
   * ```
   */
  forkAGist(gistId: string): Promise<void>;
  /**
   * Get the raw content of a gist file.
   *
   * @param options - Options for getting raw gist file content
   * @returns Raw content of the gist file
   *
   * @example
   * ```ts
   * getRawGistFileContent({
   *   username: 'github_username',
   *   gistId: 'gist_id',
   *   filename: 'file_name.txt',
   * })
   * ```
   */
  getRawGistFileContent(options: {
    /**
     * The handle for the GitHub user account.
     */
    username: string;
    /**
     * The unique identifier of the gist.
     */
    gistId: string;
    /**
     * The name of the file within the gist. If not provided, the raw content of the first file in the gist will be returned.
     */
    filename?: string;
  }): Promise<any>;
  /**
   * Check if access token is provided.
   *
   * @returns Boolean indicating whether access token is provided
   */
  hasAccessToken(): boolean;
  /**
   * Generate GistFile instance.
   *
   * @param options - Options for generating GistFile
   * @returns GistFile instance
   */
  private _generateGistFile;
  /**
   * Generate array of GistFile instances.
   *
   * @param options - Options for generating GistFiles
   * @returns Array of GistFile instances
   */
  private _generateGistFiles;
  /**
   * Generate GistUser instance.
   *
   * @param options - Options for generating GistUser
   * @returns GistUser instance
   */
  private _generateGistUser;
  /**
   * Generate Gist instance.
   *
   * @param options - Options for generating Gist
   * @returns Gist instance
   */
  private _generateGist;
  /**
   * Generate array of Gist instances.
   *
   * @param options - Options for generating Gists
   * @returns Array of Gist instances
   */
  private _generateGists;
  /**
   * Generate GistCommit instance.
   *
   * @param options - Options for generating GistCommit
   * @returns GistCommit instance
   */
  private _generateCommit;
  /**
   * Generate array of GistCommit instances.
   *
   * @param options - Options for generating GistCommits
   * @returns Array of GistCommit instances
   */
  private _generateCommits;
}
//#endregion
export { CreateAGistOptions, GeastyOptions, GetGistForUserOptions, GetGistForksOrCommitsOptions, GetGistsOptions, Gist, GistCommit, GistCommitConstructorOptions, GistConstructorOptions, GistFile, GistFileConstructorOptions, GistUser, GistUserConstructorOptions, PaginationOptions, UpdateAGistOptions, Geasty as default };
//# sourceMappingURL=index.d.ts.map