@scaffold-llc/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SPINZ BUSINESS SOLUTIONS LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @scaffold-llc/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 TypeScript SDK for [Scaffold](https://scaffold.llc). Every command your assistant can run over MCP is a typed method here and an HTTP route, generated from one command list. No runtime dependencies; it needs Node 20 or later, or any runtime with `fetch`.
+
+```bash
+npm install @scaffold-llc/sdk
+```
+
+## Quickstart
+
+About five minutes, from an empty folder to a task on your board and a new project with its first deploy live. Deploys need the Paid plan.
+
+### 1. Create a token
+
+In Scaffold, create a token with Write access under Settings, then Apps and tokens, and copy the workspace id beside it. The token is shown once, so save both to your environment now.
+
+```bash
+export SCAFFOLD_TOKEN=scf_live_...
+export SCAFFOLD_WORKSPACE=wsp_...
+```
+
+### 2. Zip the app
+
+A deploy runs a Node app with a `package.json` at the root of its zip, started by its `start` script or its `main` file, and goes live once it accepts connections on `PORT` within 30 seconds. In an empty folder, this makes one:
+
+```bash
+mkdir app
+echo '{ "main": "server.js" }' > app/package.json
+echo 'require("node:http").createServer((req, res) => res.end("Pinecrest")).listen(process.env.PORT);' > app/server.js
+(cd app && zip -r ../pinecrest-web.zip .)
+```
+
+### 3. Write the script
+
+In the same folder, run `npm install @scaffold-llc/sdk` and save this as `ship.mts`:
+
+```ts
+import { readFile } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
+import { Scaffold } from "@scaffold-llc/sdk";
+
+// Reads SCAFFOLD_TOKEN from the environment
+const scaffold = new Scaffold();
+const workspace_id = process.env.SCAFFOLD_WORKSPACE!;
+
+// Plan: put the work on the board
+const task = await scaffold.task.create({
+  workspace_id,
+  title: "Ship the booking page",
+  status: "doing",
+  labels: ["launch"],
+});
+console.log(`Task ${task.key} is on the board`);
+
+// Project: create the project the work ships in
+const project = await scaffold.project.create({
+  workspace_id,
+  name: "pinecrest-web",
+});
+console.log(`Project ${project.slug} is ready at ${project.hostname}`);
+
+// Deploy: upload the app's code and deploy it
+const archive = await readFile("pinecrest-web.zip");
+await scaffold.source.upload({ project_id: project.id, archive });
+const deploy = await scaffold.deploy.create({ project_id: project.id });
+
+// Logs: print the build's steps until it is live or failed
+let after: number | undefined;
+for (;;) {
+  const page = await scaffold.deploy.logs({ deploy_id: deploy.id, kind: "build", after });
+  for (const line of page.lines) console.log(line.text);
+  if (page.done) break;
+  after = page.next;
+  await sleep(1000);
+}
+const built = await scaffold.deploy.get({ deploy_id: deploy.id });
+if (built.status !== "live") throw new Error(`Deploy ${built.id} failed: ${built.failure}`);
+console.log(`Deploy ${built.id} is live at ${built.url}`);
+
+// Hand off: move the task to review
+await scaffold.task.move({ task_id: task.id, column: "review" });
+console.log("The task is in review");
+```
+
+### 4. Run it
+
+```bash
+npx tsx ship.mts
+```
+
+You should see the task and the project, the build's steps, the deploy's address, and the task in review. In the console the project is live, the task is in review, and the activity rail shows each change as yours, with Undo.
+
+A project's name must be new in its workspace, so change `pinecrest-web` before you run the file again.
+
+## Usage
+
+```ts
+import { Scaffold, ScaffoldError } from "@scaffold-llc/sdk";
+
+const scaffold = new Scaffold({
+  token: process.env.SCAFFOLD_TOKEN, // the default
+  baseUrl: "https://scaffold.llc", // the default
+  timeout: 30_000, // milliseconds per request
+  maxRetries: 2, // for 429 and 5xx answers, with backoff
+  version: "2026-10-01", // the default, sent as Scaffold-Version
+});
+```
+
+- **Methods** are `scaffold.<resource>.<action>(input)`, named like the command: `scaffold.task.create()` is the `task_create` MCP action and `POST /v1/tasks`. Input is one object with the HTTP API's field names; path, query and body fields go where the route takes them.
+- **Lists** like `scaffold.task.list()` answer one page of `data` with `has_more` and `next_cursor` when awaited. Loop with `for await` and the SDK fetches each next page as you reach it.
+- **Errors** throw a `ScaffoldError` with the HTTP status, the error's `type`, `message`, `param`, `requestId` and `details`, and `retryAfter` in seconds when the answer asked for a wait.
+- **Writes** take an idempotency key as a second argument, `{ idempotencyKey: "launch-2026-10-29" }`, so a retried write returns the first result instead of running twice. Without one the SDK sends its own, so its retries of a write never run it twice.
+- **Types** for every schema in the API are exported by name, like `import type { Task, Run } from "@scaffold-llc/sdk"`.
+
+The full guide is at [scaffold.llc/docs/sdk](https://scaffold.llc/docs/sdk), and every method is in the [command map](https://scaffold.llc/docs/commands).
+
+## Contributing
+
+This repository mirrors `sdk/` of Scaffold's platform repository, where the API is built. `src/generated` comes from the platform's OpenAPI document and command catalog by `npm run generate`, which only runs there, and its CI fails when the committed output is stale. So a change to the API reaches this SDK in the same merge request that makes it.
+
+Issues and pull requests are welcome here for the runtime in `src/client.ts`, the tests and the docs; we apply accepted changes upstream, and the next mirror carries them back.
+
+**Versions.** Every mirror that changes `src/` or `package.json` publishes a release from GitHub Actions, with npm provenance. The version is `major.minor` from `package.json` and the workflow's run number as the patch, so a spec change that only adds methods or fields needs no bump. A change that removes or renames a method or field, or narrows a type, bumps the minor in `package.json` while the SDK is 0.x, and the major from 1.0, in the same merge request. Leave the patch at 0.
+
+```bash
+npm ci
+npm run typecheck
+npm test
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+import { type ErrorCode, type Methods } from "./generated/methods.js";
+/** The API version this SDK was built for. */
+export declare const API_VERSION = "2026-10-01";
+export interface ScaffoldOptions {
+    /** A token from Settings, then Apps and tokens. Defaults to `SCAFFOLD_TOKEN`. */
+    token?: string;
+    /** Defaults to `https://scaffold.llc`. */
+    baseUrl?: string;
+    /** Milliseconds per request. Defaults to `30000`. */
+    timeout?: number;
+    /** Retries for 429 and 5xx answers, with backoff. Defaults to `2`. */
+    maxRetries?: number;
+    /** The API version every request sends as `Scaffold-Version`. Defaults to the SDK's own, `2026-10-01`. */
+    version?: string;
+}
+export interface WriteOptions {
+    /** A retried write with the same key returns the first result instead of running twice. Defaults to a new key per call, which the SDK's own retries reuse. */
+    idempotencyKey?: string;
+}
+export interface Route {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    /** A read that answers a page of `data`, paged by `starting_after`. */
+    list?: boolean;
+    /** The input field sent as the raw body, a zip, instead of the JSON body. */
+    zip?: string;
+    /** A write that takes `Idempotency-Key`, so sending it again never runs it twice. */
+    idempotent?: boolean;
+}
+/** A failed call, with the same `type` as the HTTP error body. */
+export declare class ScaffoldError extends Error {
+    readonly status: number;
+    /** `unexpected_response` when something other than Scaffold answered, like a proxy. */
+    readonly type: ErrorCode | "unexpected_response";
+    /** The input field at fault, like `title`. */
+    readonly param: string | undefined;
+    /** What support finds the failure by. */
+    readonly requestId: string | undefined;
+    readonly details: unknown;
+    /** Seconds the answer asked to wait before trying again. */
+    readonly retryAfter: number | undefined;
+    name: string;
+    constructor(status: number, 
+    /** `unexpected_response` when something other than Scaffold answered, like a proxy. */
+    type: ErrorCode | "unexpected_response", message: string, 
+    /** The input field at fault, like `title`. */
+    param: string | undefined, 
+    /** What support finds the failure by. */
+    requestId: string | undefined, details: unknown, 
+    /** Seconds the answer asked to wait before trying again. */
+    retryAfter: number | undefined);
+}
+/** One page when awaited; with `for await`, every item, fetching each next page as you reach it. */
+export declare class List<Page, Item> implements PromiseLike<Page>, AsyncIterable<Item> {
+    #private;
+    private readonly fetchPage;
+    constructor(fetchPage: (startingAfter?: string) => Promise<Page>);
+    then<A = Page, B = never>(onFulfilled?: ((page: Page) => A | PromiseLike<A>) | null, onRejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    [Symbol.asyncIterator](): AsyncIterator<Item>;
+}
+export interface Scaffold extends Methods {
+}
+/** The Scaffold API client: `scaffold.<resource>.<action>(input)` for every public command. */
+export declare class Scaffold {
+    #private;
+    constructor(options?: ScaffoldOptions);
+}

package/dist/client.js

@@ -0,0 +1,138 @@
+import { COMMANDS } from "./generated/methods.js";
+/** The API version this SDK was built for. */
+export const API_VERSION = "2026-10-01";
+/** A failed call, with the same `type` as the HTTP error body. */
+export class ScaffoldError extends Error {
+    status;
+    type;
+    param;
+    requestId;
+    details;
+    retryAfter;
+    name = "ScaffoldError";
+    constructor(status, 
+    /** `unexpected_response` when something other than Scaffold answered, like a proxy. */
+    type, message, 
+    /** The input field at fault, like `title`. */
+    param, 
+    /** What support finds the failure by. */
+    requestId, details, 
+    /** Seconds the answer asked to wait before trying again. */
+    retryAfter) {
+        super(message);
+        this.status = status;
+        this.type = type;
+        this.param = param;
+        this.requestId = requestId;
+        this.details = details;
+        this.retryAfter = retryAfter;
+    }
+}
+/** One page when awaited; with `for await`, every item, fetching each next page as you reach it. */
+export class List {
+    fetchPage;
+    #first;
+    constructor(fetchPage) {
+        this.fetchPage = fetchPage;
+    }
+    then(onFulfilled, onRejected) {
+        this.#first ??= this.fetchPage();
+        return this.#first.then(onFulfilled, onRejected);
+    }
+    async *[Symbol.asyncIterator]() {
+        let page = await this;
+        for (;;) {
+            const { data, has_more, next_cursor } = page;
+            yield* data;
+            if (!has_more || typeof next_cursor !== "string")
+                return;
+            page = await this.fetchPage(next_cursor);
+        }
+    }
+}
+/** The Scaffold API client: `scaffold.<resource>.<action>(input)` for every public command. */
+export class Scaffold {
+    #token;
+    #baseUrl;
+    #timeout;
+    #maxRetries;
+    #version;
+    constructor(options = {}) {
+        const env = globalThis.process?.env;
+        this.#token = options.token ?? env?.SCAFFOLD_TOKEN;
+        this.#baseUrl = (options.baseUrl ?? "https://scaffold.llc").replace(/\/+$/, "");
+        this.#timeout = options.timeout ?? 30_000;
+        this.#maxRetries = options.maxRetries ?? 2;
+        this.#version = options.version ?? API_VERSION;
+        for (const [resource, actions] of Object.entries(COMMANDS)) {
+            const methods = Object.entries(actions).map(([action, route]) => {
+                const call = (input = {}, options = {}) => (route.list ? new List((startingAfter) => this.#call(route, startingAfter === undefined ? input : { ...input, starting_after: startingAfter }, options)) : this.#call(route, input, options));
+                return [action, call];
+            });
+            Object.assign(this, { [resource]: Object.fromEntries(methods) });
+        }
+    }
+    async #call(route, input, options) {
+        const rest = { ...input };
+        const path = route.path.replace(/\{(\w+)\}/g, (_, name) => {
+            const value = rest[name];
+            if (value === undefined)
+                throw new TypeError(`${route.method} ${route.path} needs ${name}`);
+            delete rest[name];
+            return encodeURIComponent(String(value));
+        });
+        const url = new URL(this.#baseUrl + path);
+        const headers = { Accept: "application/json", "Scaffold-Version": this.#version };
+        if (this.#token)
+            headers.Authorization = `Bearer ${this.#token}`;
+        if (route.idempotent)
+            headers["Idempotency-Key"] = options.idempotencyKey ?? crypto.randomUUID();
+        let body;
+        if (route.method === "GET" || route.method === "DELETE") {
+            // A query string has no null, so a null field is left out like an undefined one.
+            for (const [key, value] of Object.entries(rest))
+                if (value !== undefined && value !== null)
+                    url.searchParams.set(key, String(value));
+        }
+        else if (route.zip !== undefined) {
+            headers["Content-Type"] = "application/zip";
+            body = rest[route.zip];
+        }
+        else {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(rest);
+        }
+        for (let attempt = 0;; attempt++) {
+            const response = await fetch(url, { method: route.method, headers, body, signal: AbortSignal.timeout(this.#timeout) });
+            if (response.ok)
+                return response.headers.get("Content-Type")?.includes("json") ? response.json() : response.blob();
+            const error = await failure(response);
+            // A 429 or 503 never ran. A 501 answers the same until the platform changes. Any other 5xx
+            // is sent again only when that cannot run it twice.
+            const retryable = response.status === 429 || response.status === 503 || (response.status >= 500 && response.status !== 501 && (route.method === "GET" || route.idempotent));
+            if (!retryable || attempt >= this.#maxRetries)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, (error.retryAfter ?? backoff(attempt)) * 1000));
+        }
+    }
+}
+/** Seconds before retry `attempt + 1` when the answer named no wait: about 0.5, 1, 2 and on, with jitter. */
+const backoff = (attempt) => 0.5 * 2 ** attempt * (0.5 + Math.random() / 2);
+async function failure(response) {
+    const text = await response.text();
+    const header = response.headers.get("Retry-After");
+    const retryAfter = header === null || Number.isNaN(Number(header)) ? undefined : Number(header);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = undefined;
+    }
+    const error = parsed?.error;
+    if (typeof error?.type === "string" && typeof error.message === "string") {
+        const text = (value) => (typeof value === "string" ? value : undefined);
+        return new ScaffoldError(response.status, error.type, error.message, text(error.param), text(error.request_id), error.details, retryAfter);
+    }
+    return new ScaffoldError(response.status, "unexpected_response", `HTTP ${response.status}: ${text.slice(0, 200)}`, undefined, undefined, undefined, retryAfter);
+}