@once-agent/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,240 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+const DEFAULT_BASE_URL = "https://once-q18-cloud.pennywatch.workers.dev";
+export class OnceError extends Error {
+    status;
+    code;
+    body;
+    retryAfter;
+    constructor(message, options = {}) {
+        super(message, {
+            cause: options.cause
+        });
+        this.name = "OnceError";
+        this.status = options.status;
+        this.code = options.code;
+        this.body = options.body;
+        this.retryAfter = options.retryAfter;
+    }
+}
+export class OnceTimeoutError extends OnceError {
+    constructor(message = "Once request timed out", cause) {
+        super(message, {
+            code: "timeout",
+            cause
+        });
+        this.name = "OnceTimeoutError";
+    }
+}
+export class OnceNetworkError extends OnceError {
+    constructor(message = "Could not reach Once", cause) {
+        super(message, {
+            code: "network_error",
+            cause
+        });
+        this.name = "OnceNetworkError";
+    }
+}
+export class Once {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    networkRetries;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ??
+            process.env.ONCE_API_KEY;
+        if (!apiKey) {
+            throw new OnceError("Missing Once API key. Set ONCE_API_KEY or pass { apiKey }.", {
+                code: "missing_api_key"
+            });
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ??
+            process.env.ONCE_BASE_URL ??
+            DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs =
+            options.timeoutMs ?? 10_000;
+        this.networkRetries =
+            options.networkRetries ?? 2;
+    }
+    /**
+     * Generate a deterministic Once operation ID.
+     *
+     * Same inputs => same ID.
+     *
+     * Example:
+     * Once.id("refund", "order_123")
+     */
+    static id(...parts) {
+        if (parts.length === 0) {
+            throw new OnceError("Once.id() requires at least one value.", {
+                code: "invalid_operation_id"
+            });
+        }
+        const values = parts.map(part => {
+            if (typeof part === "string") {
+                return part;
+            }
+            if (typeof part === "number" &&
+                Number.isSafeInteger(part)) {
+                return String(part);
+            }
+            throw new OnceError("Once.id() parts must be strings or safe integers.", {
+                code: "invalid_operation_id"
+            });
+        });
+        /*
+         * Once operation-ID semantic encoding v1.
+         *
+         * Hash input:
+         *   "once-id-v1\\0"
+         *   uint32be(part count)
+         *   repeated:
+         *     uint32be(UTF-8 byte length)
+         *     UTF-8 bytes
+         *
+         * Length-prefixing prevents different part
+         * boundaries from producing identical hash input.
+         */
+        const hashState = createHash("sha256");
+        hashState.update("once-id-v1\u0000", "utf8");
+        const partCount = Buffer.allocUnsafe(4);
+        partCount.writeUInt32BE(values.length, 0);
+        hashState.update(partCount);
+        for (const value of values) {
+            const bytes = Buffer.from(value, "utf8");
+            if (bytes.length >
+                0xffffffff) {
+                throw new OnceError("Once.id() part is too large.", {
+                    code: "invalid_operation_id"
+                });
+            }
+            const length = Buffer.allocUnsafe(4);
+            length.writeUInt32BE(bytes.length, 0);
+            hashState.update(length);
+            hashState.update(bytes);
+        }
+        const hash = hashState
+            .digest("hex")
+            .slice(0, 32);
+        const prefix = values[0]
+            .replace(/[A-Z]/g, character => character.toLowerCase())
+            .replace(/[^a-z0-9._:-]+/g, "-")
+            .replace(/^[^a-z0-9]+/, "")
+            .replace(/-+$/g, "")
+            .slice(0, 48) || "operation";
+        return `${prefix}:${hash}`;
+    }
+    id(...parts) {
+        return Once.id(...parts);
+    }
+    async execute(input) {
+        if (!input.operationId) {
+            throw new OnceError("operationId is required.", {
+                code: "invalid_operation_id"
+            });
+        }
+        if (!input.provider) {
+            throw new OnceError("provider is required.", {
+                code: "invalid_provider"
+            });
+        }
+        return this.request("/v1/execute", {
+            method: "POST",
+            body: JSON.stringify({
+                operation_id: input.operationId,
+                provider: input.provider,
+                action: input.action
+            })
+        });
+    }
+    async truth(operationId) {
+        if (!operationId) {
+            throw new OnceError("operationId is required.", {
+                code: "invalid_operation_id"
+            });
+        }
+        return this.request(`/v1/truth/${encodeURIComponent(operationId)}`, {
+            method: "GET"
+        });
+    }
+    async request(path, init) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.networkRetries; attempt++) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const response = await fetch(`${this.baseUrl}${path}`, {
+                    ...init,
+                    signal: controller.signal,
+                    headers: {
+                        authorization: `Bearer ${this.apiKey}`,
+                        "content-type": "application/json",
+                        ...init.headers
+                    }
+                });
+                clearTimeout(timeout);
+                const raw = await response.text();
+                let body = null;
+                if (raw) {
+                    try {
+                        body = JSON.parse(raw);
+                    }
+                    catch {
+                        body = {
+                            message: raw
+                        };
+                    }
+                }
+                if (!response.ok) {
+                    const retryAfterHeader = response.headers.get("retry-after");
+                    const retryAfter = retryAfterHeader !== null
+                        ? Number(retryAfterHeader)
+                        : undefined;
+                    const code = body?.error ??
+                        body?.result ??
+                        `http_${response.status}`;
+                    const message = body?.message ??
+                        body?.error ??
+                        body?.result ??
+                        `Once returned HTTP ${response.status}`;
+                    throw new OnceError(String(message), {
+                        status: response.status,
+                        code: String(code),
+                        body,
+                        retryAfter: Number.isFinite(retryAfter)
+                            ? retryAfter
+                            : undefined
+                    });
+                }
+                return body;
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                // Once returned a real HTTP response.
+                // Do not hide or automatically transform it.
+                if (error instanceof OnceError) {
+                    throw error;
+                }
+                lastError = error;
+                const aborted = error instanceof Error &&
+                    error.name === "AbortError";
+                if (attempt <
+                    this.networkRetries) {
+                    await sleep(150 * Math.pow(2, attempt));
+                    continue;
+                }
+                if (aborted) {
+                    throw new OnceTimeoutError(`Once request timed out after ${this.timeoutMs}ms`, error);
+                }
+                throw new OnceNetworkError("Could not reach Once after safe network retries", error);
+            }
+        }
+        throw new OnceNetworkError("Could not reach Once", lastError);
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export default Once;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/protect.d.ts

@@ -0,0 +1,8 @@
+export type ProtectOptions = {
+    includeAll?: boolean;
+    writePlan?: boolean;
+    writePatch?: boolean;
+    writeSnippets?: boolean;
+};
+export declare function runProtect(requestedPath: string, options?: ProtectOptions): Promise<void>;
+//# sourceMappingURL=protect.d.ts.map

package/dist/protect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protect.d.ts","sourceRoot":"","sources":["../src/protect.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAu5BF,wBAAsB,UAAU,CAC9B,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAybf"}