@getrefino/github 0.1.0-rc.5 → 0.1.0

package/dist/adapter.d.ts

@@ -1,12 +1,14 @@
 /**
- * GitHub persistence through the REST Contents API
- * (GET/PUT /repos/{owner}/{repo}/contents/{path}).
+ * GitHub persistence for the copy file.
  *
  * Why the Contents API: it reads a file with its blob SHA and writes a new
  * version as a single commit only if the SHA still matches. That gives us
  * load, conflict detection, and an understandable commit without a custom
  * git implementation.
  *
+ * The HTTP itself lives in `file-store.ts`, which the article document
+ * service also uses, so copy and content commit through one code path.
+ *
  * Docs: https://docs.github.com/en/rest/repos/contents
  */
 import type { ContentAdapter } from "@getrefino/core";

package/dist/adapter.js

@@ -1,62 +1,16 @@
-import { ContentConflictError, ContentError, buildCommitMessage, parseCopy, planSave } from "@getrefino/core";
+import { ContentConflictError, ContentError, buildCommitMessage, isContentError, parseCopy, planSave, } from "@getrefino/core";
+import { createGitHubFileClient } from "./file-store.js";
 import { resolveOptions } from "./options.js";
-function encodePath(path) {
-    return path.split("/").map(encodeURIComponent).join("/");
-}
-function decodeBase64(text) {
-    return Buffer.from(text.replace(/\s/g, ""), "base64").toString("utf8");
-}
-function encodeBase64(text) {
-    return Buffer.from(text, "utf8").toString("base64");
-}
 export function createGitHubContentAdapter(options) {
     const resolved = resolveOptions(options);
-    const doFetch = resolved.fetch ?? ((...args) => globalThis.fetch(...args));
-    const fileUrl = `${resolved.apiBaseUrl}/repos/${encodeURIComponent(resolved.owner)}/${encodeURIComponent(resolved.repo)}/contents/${encodePath(resolved.path)}`;
-    const location = `${resolved.owner}/${resolved.repo}@${resolved.branch}:${resolved.path}`;
-    function headers(extra = {}) {
-        return {
-            accept: "application/vnd.github+json",
-            authorization: `Bearer ${resolved.token}`,
-            "x-github-api-version": resolved.apiVersion,
-            "user-agent": "refino-github-adapter",
-            ...extra,
-        };
-    }
-    /** Never let the token leak through an error message. */
-    function scrub(text) {
-        return text.split(resolved.token).join("[redacted]");
-    }
-    async function readError(response) {
-        try {
-            const body = (await response.json());
-            return scrub(body.message ?? `HTTP ${response.status}`);
-        }
-        catch {
-            return `HTTP ${response.status}`;
-        }
-    }
+    const client = createGitHubFileClient(resolved);
+    const location = client.location(resolved.path);
     async function readCurrent() {
-        const url = `${fileUrl}?ref=${encodeURIComponent(resolved.branch)}`;
-        const response = await doFetch(url, { method: "GET", headers: headers(), cache: "no-store" });
-        if (response.status === 404) {
+        const file = await client.readFile(resolved.path);
+        if (!file) {
             throw new ContentError("NOT_FOUND", `Copy file not found at ${location}. Check the repository, branch and path.`);
         }
-        if (response.status === 401 || response.status === 403) {
-            throw new ContentError("ADAPTER_ERROR", `GitHub rejected the token (HTTP ${response.status}). It needs Contents read/write on ${resolved.owner}/${resolved.repo}.`);
-        }
-        if (!response.ok) {
-            throw new ContentError("ADAPTER_ERROR", `GitHub read failed: ${await readError(response)}`);
-        }
-        const file = (await response.json());
-        if (file.type !== "file" || typeof file.sha !== "string") {
-            throw new ContentError("ADAPTER_ERROR", `${location} is not a file.`);
-        }
-        if (file.encoding !== "base64" || typeof file.content !== "string") {
-            throw new ContentError("ADAPTER_ERROR", `${location} is too large to edit through the Contents API (1 MB limit).`);
-        }
-        const text = decodeBase64(file.content);
-        return { text, content: parseCopy(text), revision: file.sha };
+        return { text: file.text, content: parseCopy(file.text), revision: file.revision };
     }
     return {
         name: "github",
@@ -73,43 +27,28 @@ export function createGitHubContentAdapter(options) {
             const message = resolved.commitMessage
                 ? resolved.commitMessage({ changedIds: plan.changedIds })
                 : buildCommitMessage(plan.changedIds);
-            const body = {
-                message,
-                content: encodeBase64(plan.text),
-                sha: current.revision,
-                branch: resolved.branch,
-            };
-            if (resolved.committer)
-                body.committer = resolved.committer;
-            if (resolved.author)
-                body.author = resolved.author;
-            const response = await doFetch(fileUrl, {
-                method: "PUT",
-                headers: headers({ "content-type": "application/json" }),
-                body: JSON.stringify(body),
-            });
-            if (response.status === 409) {
-                // GitHub compared the SHA we sent with the file and found it moved.
-                const latest = await readCurrent();
-                throw new ContentConflictError("The copy file changed in the repository while you were editing. Reload the latest copy and reapply your edits.", { content: latest.content, revision: latest.revision });
-            }
-            if (response.status === 401 || response.status === 403) {
-                throw new ContentError("ADAPTER_ERROR", `GitHub refused the commit (HTTP ${response.status}). The token needs Contents read/write on ${resolved.owner}/${resolved.repo}, and the branch must not block direct pushes.`);
+            let written;
+            try {
+                written = await client.writeFile({
+                    path: resolved.path,
+                    text: plan.text,
+                    baseRevision: current.revision,
+                    message,
+                });
             }
-            if (!response.ok) {
-                throw new ContentError("ADAPTER_ERROR", `GitHub commit failed: ${await readError(response)}`);
-            }
-            const result = (await response.json());
-            const newSha = result.content?.sha;
-            if (typeof newSha !== "string") {
-                throw new ContentError("ADAPTER_ERROR", "GitHub commit succeeded but returned no file SHA.");
+            catch (error) {
+                // GitHub compared the SHA we sent with the file and found it moved.
+                // The editor gets the latest copy back so it can rebase in place.
+                if (isContentError(error) && error.code === "CONFLICT") {
+                    const latest = await readCurrent();
+                    throw new ContentConflictError("The copy file changed in the repository while you were editing. Reload the latest copy and reapply your edits.", { content: latest.content, revision: latest.revision });
+                }
+                throw error;
             }
-            const commitSha = result.commit?.sha ?? "";
-            const commitUrl = result.commit?.html_url;
             return {
                 status: "saved",
-                snapshot: { content: plan.content, revision: newSha },
-                commit: commitUrl ? { sha: commitSha, message, url: commitUrl } : { sha: commitSha, message },
+                snapshot: { content: plan.content, revision: written.revision },
+                ...(written.commit ? { commit: written.commit } : {}),
             };
         },
     };

package/dist/file-store.d.ts

@@ -0,0 +1,29 @@
+import type { SourceFile, SourceFileStore, SourceFileWrite, SourceFileWriteResult } from "@getrefino/core/documents";
+import type { GitHubCommitIdentity } from "./options.js";
+export interface GitHubFileStoreOptions {
+    /** Fine-grained token with **Contents: Read and write** on this one repository. Server-side only. */
+    readonly token: string;
+    readonly owner: string;
+    readonly repo: string;
+    readonly branch: string;
+    readonly apiBaseUrl?: string;
+    readonly apiVersion?: string;
+    readonly fetch?: typeof fetch;
+    readonly committer?: GitHubCommitIdentity;
+    readonly author?: GitHubCommitIdentity;
+}
+/**
+ * The raw GitHub calls, shared by the copy adapter and the document store.
+ * `readFile` reports a missing file as `null` so each caller can say what a
+ * missing file means for it.
+ */
+export interface GitHubFileClient {
+    readonly location: (path: string) => string;
+    readFile(path: string): Promise<(SourceFile & {
+        readonly tooLarge?: false;
+    }) | null>;
+    writeFile(write: SourceFileWrite): Promise<SourceFileWriteResult>;
+}
+export declare function createGitHubFileClient(options: GitHubFileStoreOptions): GitHubFileClient;
+/** A `SourceFileStore` over one repository and branch. */
+export declare function createGitHubFileStore(options: GitHubFileStoreOptions): SourceFileStore;

package/dist/file-store.js

@@ -0,0 +1,113 @@
+import { ContentError } from "@getrefino/core";
+import { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, validateRepoPath } from "./options.js";
+function encodePath(path) {
+    return path.split("/").map(encodeURIComponent).join("/");
+}
+function decodeBase64(text) {
+    return Buffer.from(text.replace(/\s/g, ""), "base64").toString("utf8");
+}
+function encodeBase64(text) {
+    return Buffer.from(text, "utf8").toString("base64");
+}
+export function createGitHubFileClient(options) {
+    const token = options.token;
+    const apiBaseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+    const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+    const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+    const repoUrl = `${apiBaseUrl}/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/contents`;
+    const location = (path) => `${options.owner}/${options.repo}@${options.branch}:${path}`;
+    function headers(extra = {}) {
+        return {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${token}`,
+            "x-github-api-version": apiVersion,
+            "user-agent": "refino-github-adapter",
+            ...extra,
+        };
+    }
+    /** Never let the token leak through an error message. */
+    function scrub(text) {
+        return text.split(token).join("[redacted]");
+    }
+    async function readError(response) {
+        try {
+            const body = (await response.json());
+            return scrub(body.message ?? `HTTP ${response.status}`);
+        }
+        catch {
+            return `HTTP ${response.status}`;
+        }
+    }
+    function rejected(response) {
+        return new ContentError("ADAPTER_ERROR", `GitHub rejected the token (HTTP ${response.status}). It needs Contents read/write on ${options.owner}/${options.repo}.`);
+    }
+    return {
+        location,
+        async readFile(path) {
+            const safePath = validateRepoPath(path);
+            const url = `${repoUrl}/${encodePath(safePath)}?ref=${encodeURIComponent(options.branch)}`;
+            const response = await doFetch(url, { method: "GET", headers: headers(), cache: "no-store" });
+            if (response.status === 404)
+                return null;
+            if (response.status === 401 || response.status === 403)
+                throw rejected(response);
+            if (!response.ok) {
+                throw new ContentError("ADAPTER_ERROR", `GitHub read failed: ${await readError(response)}`);
+            }
+            const file = (await response.json());
+            if (file.type !== "file" || typeof file.sha !== "string") {
+                throw new ContentError("ADAPTER_ERROR", `${location(safePath)} is not a file.`);
+            }
+            if (file.encoding !== "base64" || typeof file.content !== "string") {
+                throw new ContentError("ADAPTER_ERROR", `${location(safePath)} is too large to edit through the Contents API (1 MB limit).`);
+            }
+            return { text: decodeBase64(file.content), revision: file.sha };
+        },
+        async writeFile(write) {
+            const safePath = validateRepoPath(write.path);
+            const body = {
+                message: write.message,
+                content: encodeBase64(write.text),
+                sha: write.baseRevision,
+                branch: options.branch,
+            };
+            if (options.committer)
+                body.committer = options.committer;
+            if (options.author)
+                body.author = options.author;
+            const response = await doFetch(`${repoUrl}/${encodePath(safePath)}`, {
+                method: "PUT",
+                headers: headers({ "content-type": "application/json" }),
+                body: JSON.stringify(body),
+            });
+            if (response.status === 409) {
+                throw new ContentError("CONFLICT", `${safePath} changed in the repository while you were editing. Reload the latest content and reapply your edits.`, { path: safePath });
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new ContentError("ADAPTER_ERROR", `GitHub refused the commit (HTTP ${response.status}). The token needs Contents read/write on ${options.owner}/${options.repo}, and the branch must not block direct pushes.`);
+            }
+            if (!response.ok) {
+                throw new ContentError("ADAPTER_ERROR", `GitHub commit failed: ${await readError(response)}`);
+            }
+            const result = (await response.json());
+            const newSha = result.content?.sha;
+            if (typeof newSha !== "string") {
+                throw new ContentError("ADAPTER_ERROR", "GitHub commit succeeded but returned no file SHA.");
+            }
+            const commitUrl = result.commit?.html_url;
+            const commit = commitUrl
+                ? { sha: result.commit?.sha ?? "", message: write.message, url: commitUrl }
+                : { sha: result.commit?.sha ?? "", message: write.message };
+            return { revision: newSha, commit };
+        },
+    };
+}
+/** A `SourceFileStore` over one repository and branch. */
+export function createGitHubFileStore(options) {
+    const client = createGitHubFileClient(options);
+    return {
+        name: "github",
+        readFile: (path) => client.readFile(path),
+        writeFile: (write) => client.writeFile(write),
+    };
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { createGitHubContentAdapter } from "./adapter.js";
+export { createGitHubFileClient, createGitHubFileStore } from "./file-store.js";
+export type { GitHubFileClient, GitHubFileStoreOptions } from "./file-store.js";
 export { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, GITHUB_ENV, githubOptionsFromEnv, validateRepoPath, } from "./options.js";
 export type { GitHubCommitIdentity, GitHubContentAdapterOptions } from "./options.js";
 export { GitHubRepositoryError, MAX_BLOB_BYTES, createGitHubRepository, isGitHubRepositoryError } from "./repository.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { createGitHubContentAdapter } from "./adapter.js";
+export { createGitHubFileClient, createGitHubFileStore } from "./file-store.js";
 export { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, GITHUB_ENV, githubOptionsFromEnv, validateRepoPath, } from "./options.js";
 export { GitHubRepositoryError, MAX_BLOB_BYTES, createGitHubRepository, isGitHubRepositoryError } from "./repository.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/github",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0",
   "description": "GitHub persistence adapter for Refino: reads and commits the canonical copy file through the GitHub Contents API, so the repository stays the source of truth.",
   "keywords": [
     "refino",
@@ -36,7 +36,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@getrefino/core": "0.1.0-rc.5"
+    "@getrefino/core": "0.1.0"
   },
   "devDependencies": {
     "@types/node": "22.20.2",