@goodfellow-cms/github 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,8 +1,24 @@
-import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, OwnerAccess, PagesDomains, SetupHost, SiteEditors, SiteUpdates, StorageLike, TokenLink, WriteOptions } from "@goodfellow-cms/core";
+import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, OwnerAccess, PagesDomains, RedirectOptions, SetupHost, SignInError, SiteDrafts, SiteEditors, SiteUpdates, StorageLike, TokenLink, WriteOptions } from "@goodfellow-cms/core";
+//#region src/sign-in.d.ts
+/** The sign-in worker Goodfellow runs for every site. Sites can run their own and name it in `github({ signIn })`. */
+export declare const GOODFELLOW_SIGN_IN = "https://sign-in.goodfellow-cms.workers.dev";
+/** The page's address and how to change it. Replaceable in tests. */
+interface BrowserLocation {
+  href(): string;
+  /** Navigates away, for example to GitHub's sign-in page. */
+  assign(url: string): void;
+  /** Changes the address without reloading, for example to remove the sign-in's details after coming back. */
+  replace(url: string): void;
+}
+//#endregion
 //#region src/api.d.ts
+/** A token that renews itself, such as one from the sign-in worker. `refresh` asks for a new one even if it hasn't expired. */
+type TokenSource = (options?: {
+  refresh?: boolean;
+}) => Promise<string>;
 interface ApiOptions {
   apiUrl: string;
-  token: string;
+  token: string | TokenSource;
   fetch: typeof fetch;
 }
 //#endregion
@@ -15,6 +31,17 @@ interface GitHubBackendOptions {
   onSignOut: () => void;
   /** Where to create the owner token, which can change editors and GitHub Pages settings. */
   ownerTokenLink: TokenLink;
+  /** Signs in as an owner through the sign-in worker instead of with a token, where it's available. */
+  ownerRedirect?: (options?: RedirectOptions) => Promise<void>;
+  /**
+   * Who commits name as their author. Set when the token is an app's
+   * installation token from the sign-in worker, whose commits would otherwise
+   * name the app. Commits are then made with Git's data API, which can name them.
+   */
+  author?: {
+    name: string;
+    email: string;
+  };
 }
 /**
  * The site's files on GitHub. Reads come from the commit `revision()` last
@@ -27,25 +54,47 @@ export declare class GitHubBackend implements GitBackend {
   readonly editors: SiteEditors;
   readonly ownerAccess: OwnerAccess;
   readonly updates: SiteUpdates;
+  readonly drafts: SiteDrafts;
+  private readonly options;
   private readonly api;
   private readonly repo;
   private readonly branch;
   private readonly onSignOut;
+  private readonly author?;
+  private readonly owner;
   private pinned?;
   private readonly trees;
+  /** Each file's size in bytes at a commit, which GitHub lists with its tree. */
+  private readonly treeSizes;
   private readonly blobs;
   constructor(options: GitHubBackendOptions);
+  /** Drafts on branches of the repository, with pull requests for review. */
+  private draftHost;
   revision(): Promise<string>;
   /** Path → blob id for every file at a commit. Commits never change, so this is cached. */
   private tree;
   private currentTree;
   read(path: string): Promise<string | undefined>;
   private readFrom;
+  /** Reads many text files in a few GraphQL requests rather than one request each. */
+  readFiles(paths: string[]): Promise<Map<string, string>>;
   readBytes(path: string): Promise<Uint8Array | undefined>;
   list(dir: string): Promise<string[]>;
-  write(changes: FileChange[], { message, expectedRevision }: WriteOptions): Promise<{
+  fileSizes(dir: string): Promise<Map<string, number>>;
+  /** Uses an owner's sign-in through the worker for editors and GitHub Pages settings, until it's forgotten. */
+  useOwnerSignIn(token: TokenSource, end: () => void): void;
+  /** Remembers why an owner's sign-in through the worker didn't work, which the Editors and Domain screens show. */
+  ownerSignInFailed(error: unknown): void;
+  write(changes: FileChange[], options: WriteOptions): Promise<{
     revision: string;
   }>;
+  /**
+   * Saves with Git's data API, naming the editor as the commit's author:
+   * GitHub refuses to move the branch unless the commit follows on from it, so
+   * nothing is overwritten.
+   */
+  private writeCommit;
+  private writeGraphQL;
   history(path: string, { page, perPage }?: HistoryOptions): Promise<FileVersion[]>;
   readAt(path: string, revision: string): Promise<string | undefined>;
   changedPaths(from: string, to: string): Promise<string[]>;
@@ -73,8 +122,17 @@ interface GitHubSetupOptions {
   apiUrl?: string;
   /** For GitHub Enterprise. Defaults to `https://github.com`. */
   webUrl?: string;
+  /** The sign-in worker, for "Sign in with GitHub". Defaults to Goodfellow's; `false` for token sign-in only. */
+  signIn?: string | false;
   /** For tests. */
   fetch?: typeof fetch;
+  /** For tests. */
+  storage?: {
+    local?: StorageLike;
+    session?: StorageLike;
+  };
+  /** For tests. */
+  location?: BrowserLocation;
 }
 /**
  * Links to GitHub's token pages with what creating a site needs: creating the
@@ -98,6 +156,12 @@ export interface GitHubOptions {
   apiUrl?: string;
   /** For GitHub Enterprise. Defaults to `https://github.com`. */
   webUrl?: string;
+  /**
+   * The sign-in worker, which lets editors sign in with GitHub instead of
+   * pasting a token. Defaults to Goodfellow's (`GOODFELLOW_SIGN_IN`); give the
+   * address of your own copy, or `false` for token sign-in only.
+   */
+  signIn?: string | false;
   /** For tests. */
   fetch?: typeof fetch;
   /** For tests. */
@@ -105,6 +169,8 @@ export interface GitHubOptions {
     local?: StorageLike;
     session?: StorageLike;
   };
+  /** For tests. */
+  location?: BrowserLocation;
 }
 /**
  * Links to GitHub's token page with everything filled in except the
@@ -118,4 +184,4 @@ export declare function githubTokenLinks(repo: string, webUrl?: string): {
 /** Sign-in and storage for a site whose repository is on GitHub. */
 export declare function github(options: GitHubOptions): GitHost;
 //#endregion
-export type { GitHubSetupOptions };
+export type { BrowserLocation, GitHubSetupOptions };