@reviewflow/sdk 0.0.0-stage → 6.21.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Christophe Hurpeau <302891+christophehurpeau@users.noreply.github.com> (https://christophe.hurpeau.com)
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted, provided that the
+above copyright notice and this permission notice appear in all
+copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
+PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @reviewflow/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The pull request model behind the [reviewflow](https://github.com/christophehurpeau/reviewflow)
+local app: diff and api types, pure utils, the GitHub layer behind a transport you
+supply, the reviewflow api client, and (node only) reading a pull request diff
+from a local git checkout.
+
+## Install
+
+```sh
+npm install @reviewflow/sdk
+```
+
+ESM only. The node entries need node `>=24.14.1`; the root entry also has a
+browser build.
+
+## Entry points
+
+| Import                  | Runs on       | What                                                                              |
+| ----------------------- | ------------- | --------------------------------------------------------------------------------- |
+| `@reviewflow/sdk`       | node, browser | types, utils, GitHub queries and edits, reviewflow api client and stream          |
+| `@reviewflow/sdk/git`   | node          | read a diff, reading order and impacts from a local checkout (runs `git`)         |
+| `@reviewflow/sdk/files` | node          | read and save a text file in place, behind validation and a changed-on-disk check |
+
+`@reviewflow/sdk/git` needs a `git` executable on `PATH`.
+
+## Wiring
+
+The sdk never authenticates nor picks an HTTP client: you inject them.
+
+```ts
+import {
+  createGitHubTransport,
+  createReviewflowClient,
+  fetchPullRequestPart,
+} from "@reviewflow/sdk";
+
+// GitHub: you send the bytes, the sdk builds the GraphQL, REST and diff calls.
+const transport = createGitHubTransport(
+  async ({ method, path, accept, body }) => {
+    const response = await fetch(`https://api.github.com/${path}`, {
+      method,
+      headers: { authorization: `Bearer ${token}`, accept },
+      body,
+    });
+    return { status: response.status, body: await response.text() };
+  },
+);
+
+const detail = await fetchPullRequestPart(
+  transport,
+  { ownerRepo: "octocat/hello-world", number: 1 },
+  "detail",
+);
+
+// reviewflow's read api, with a user's api token (`fetch` is injectable too).
+const reviewflow = createReviewflowClient({
+  url: "https://reviewflow.example",
+  token: apiToken,
+});
+```
+
+On node, `@reviewflow/sdk/git` reads the same pull request from a checkout and
+falls back to GitHub through the same transport:
+
+```ts
+import { readPullRequestDiff } from "@reviewflow/sdk/git";
+
+const diff = await readPullRequestDiff({
+  checkout: "/path/to/clone", // or null to read from GitHub only
+  transport,
+  ref: { ownerRepo: "octocat/hello-world", number: 1 },
+  head: headSha,
+  base: baseSha,
+});
+```
+
+## TypeScript
+
+The `types` condition points at the TypeScript sources (`src/`), which import
+each other with a `.ts` extension. Your `tsconfig.json` needs
+`"allowImportingTsExtensions": true` (with `noEmit` or `emitDeclarationOnly`),
+or the checker reports TS5097 inside this package.
+
+## License
+
+ISC

package/build/files-node.mjs

@@ -0,0 +1,70 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, realpathSync, writeFileSync, chmodSync, statSync, renameSync, unlinkSync, readFileSync } from 'node:fs';
+import { dirname, join, basename } from 'node:path';
+
+const isMissing = (error) => error.code === "ENOENT";
+const readCurrent = (path) => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+};
+const readEditableFile = (path) => {
+  const source = readCurrent(path);
+  return source === null ? { source: "", exists: false } : { source, exists: true };
+};
+const validationOf = async (validate, source) => {
+  try {
+    return await validate(source);
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+};
+const saveEditableFile = async ({
+  path,
+  source,
+  expectedSource,
+  validate,
+  trailingNewline = true
+}) => {
+  const text = trailingNewline && source !== "" && !source.endsWith("\n") ? `${source}
+` : source;
+  const validation = await validationOf(validate, text);
+  if ("error" in validation) {
+    return { status: "invalid", error: validation.error };
+  }
+  const current = readCurrent(path);
+  if (expectedSource !== void 0) {
+    const conflicts = expectedSource === null ? current !== null : (current ?? "") !== expectedSource;
+    if (conflicts) {
+      return {
+        status: "conflict",
+        source: current ?? "",
+        exists: current !== null
+      };
+    }
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const target = current === null ? path : realpathSync(path);
+  const temporary = join(
+    dirname(target),
+    `.${basename(target)}.${String(process.pid)}.${randomBytes(4).toString("hex")}.tmp`
+  );
+  try {
+    writeFileSync(temporary, text);
+    if (current !== null) chmodSync(temporary, statSync(target).mode & 4095);
+    renameSync(temporary, target);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+    }
+    throw error;
+  }
+  return { status: "saved", source: text, warnings: validation.warnings };
+};
+
+export { readEditableFile, saveEditableFile };
+//# sourceMappingURL=files-node.mjs.map