@sinecloud/api-client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sine Cloud
+
+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,11 @@
-# Temporary Holding Version
+# @sinecloud/api-client
 
-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.
+Shared runtime contracts for the first-party clients. Published alongside `@sinecloud/sdk` with the same version; it has no dependencies.
+
+- `waitForTerminal`: the one polling loop used by the CLI and the SDK. Read-only by design; a
+  timeout, an unreadable status or an abort raises `WaitError` so callers can classify the
+  outcome as unknown instead of failed.
+- Terminal status tables per product. `unknown` and `reconciliation` are deliberately absent:
+  they need inspection, not a retry.
+
+Nothing here performs I/O; both clients supply their own `read` function and transport.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { WaitError, waitForTerminal } from './wait.js';
+export type { WaitFailure, WaitForTerminalOptions } from './wait.js';
+export { boxExecutionTerminalStatuses, gatewayTaskTerminalStatuses, powersRunTerminalStatuses } from './statuses.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { WaitError, waitForTerminal } from './wait.js';
+export { boxExecutionTerminalStatuses, gatewayTaskTerminalStatuses, powersRunTerminalStatuses } from './statuses.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}

package/dist/statuses.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Terminal status sets for the durable work the first-party clients poll.
+ *
+ * These are contract facts, not OpenAPI data: a document can list a status enum but cannot say
+ * which values mean "stop waiting". Keeping them here means the CLI and the SDK cannot disagree
+ * about when a paid submission is finished, and `unknown`/`reconciliation` are never mistaken
+ * for failure.
+ */
+/** Box execution status: `reconciliation` still awaits financial resolution. */
+export declare const boxExecutionTerminalStatuses: Readonly<Record<string, true>>;
+/** Gateway task status: `unknown` needs inspection, not a retry. */
+export declare const gatewayTaskTerminalStatuses: Readonly<Record<string, true>>;
+/** Powers run status: `UNKNOWN` is an undetermined outcome, not a failure. */
+export declare const powersRunTerminalStatuses: Readonly<Record<string, true>>;
+//# sourceMappingURL=statuses.d.ts.map

package/dist/statuses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statuses.d.ts","sourceRoot":"","sources":["../src/statuses.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAqC,CAAC;AAE9G,oEAAoE;AACpE,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAEtE,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAEpE,CAAC"}

package/dist/statuses.js

@@ -0,0 +1,19 @@
+/**
+ * Terminal status sets for the durable work the first-party clients poll.
+ *
+ * These are contract facts, not OpenAPI data: a document can list a status enum but cannot say
+ * which values mean "stop waiting". Keeping them here means the CLI and the SDK cannot disagree
+ * about when a paid submission is finished, and `unknown`/`reconciliation` are never mistaken
+ * for failure.
+ */
+/** Box execution status: `reconciliation` still awaits financial resolution. */
+export const boxExecutionTerminalStatuses = { settled: true, released: true };
+/** Gateway task status: `unknown` needs inspection, not a retry. */
+export const gatewayTaskTerminalStatuses = {
+    completed: true, failed: true, cancelled: true, expired: true,
+};
+/** Powers run status: `UNKNOWN` is an undetermined outcome, not a failure. */
+export const powersRunTerminalStatuses = {
+    SUCCEEDED: true, PROVIDER_ERROR: true, EXECUTOR_ERROR: true, FAILED: true,
+};
+//# sourceMappingURL=statuses.js.map

package/dist/statuses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statuses.js","sourceRoot":"","sources":["../src/statuses.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,4BAA4B,GAAmC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAE9G,oEAAoE;AACpE,MAAM,CAAC,MAAM,2BAA2B,GAAmC;IACzE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI;CAC9D,CAAC;AAEF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,yBAAyB,GAAmC;IACvE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI;CAC1E,CAAC"}

package/dist/wait.d.ts

@@ -0,0 +1,29 @@
+export type WaitFailure = 'timeout' | 'unreadableStatus' | 'aborted';
+/** The wait ended without a terminal state; the work may still be running. */
+export declare class WaitError extends Error {
+    readonly reason: WaitFailure;
+    constructor(message: string, reason: WaitFailure);
+}
+export interface WaitForTerminalOptions<T> {
+    /** One read of the durable resource. Must not submit or mutate anything. */
+    read: () => Promise<T>;
+    statusOf: (value: T) => unknown;
+    terminal: Readonly<Record<string, true>>;
+    timeoutMs: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    signal?: AbortSignal;
+    onPoll?: (status: string | undefined, value: T) => void;
+}
+/**
+ * Poll a durable resource until it reaches a terminal status.
+ *
+ * The first read happens after the initial delay: the caller has just received the submission
+ * response, so an immediate read only adds a round trip. Exponential backoff caps at
+ * `maxDelayMs`. A timeout, an unreadable status or an abort raises `WaitError`; callers translate
+ * that into "unknown outcome" and must recover with the original identity instead of resending.
+ */
+export declare function waitForTerminal<T>(options: WaitForTerminalOptions<T>): Promise<T>;
+//# sourceMappingURL=wait.d.ts.map

package/dist/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAAC;AAErE,8EAA8E;AAC9E,qBAAa,SAAU,SAAQ,KAAK;IACL,QAAQ,CAAC,MAAM,EAAE,WAAW;IAAzD,YAAY,OAAO,EAAE,MAAM,EAAW,MAAM,EAAE,WAAW,EAGxD;CACF;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAChC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CACzD;AAQD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAmBvF"}

package/dist/wait.js

@@ -0,0 +1,48 @@
+/** The wait ended without a terminal state; the work may still be running. */
+export class WaitError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = 'WaitError';
+    }
+}
+function defaultSleep(milliseconds) {
+    const { promise, resolve } = Promise.withResolvers();
+    setTimeout(resolve, milliseconds);
+    return promise;
+}
+/**
+ * Poll a durable resource until it reaches a terminal status.
+ *
+ * The first read happens after the initial delay: the caller has just received the submission
+ * response, so an immediate read only adds a round trip. Exponential backoff caps at
+ * `maxDelayMs`. A timeout, an unreadable status or an abort raises `WaitError`; callers translate
+ * that into "unknown outcome" and must recover with the original identity instead of resending.
+ */
+export async function waitForTerminal(options) {
+    const now = options.now ?? (() => Date.now());
+    const sleep = options.sleep ?? defaultSleep;
+    const deadline = now() + options.timeoutMs;
+    let delay = options.initialDelayMs ?? 1_000;
+    for (;;) {
+        if (options.signal?.aborted)
+            throw new WaitError('The wait was aborted.', 'aborted');
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw new WaitError('The resource did not reach a terminal state before the deadline.', 'timeout');
+        await sleep(Math.min(delay, remaining));
+        delay = Math.min(options.maxDelayMs ?? 5_000, delay * 2);
+        if (options.signal?.aborted)
+            throw new WaitError('The wait was aborted.', 'aborted');
+        const value = await options.read();
+        const raw = options.statusOf(value);
+        const status = typeof raw === 'string' && raw !== '' ? raw : undefined;
+        options.onPoll?.(status, value);
+        if (status !== undefined && Object.hasOwn(options.terminal, status))
+            return value;
+        if (status === undefined)
+            throw new WaitError('The resource has no readable status.', 'unreadableStatus');
+    }
+}
+//# sourceMappingURL=wait.js.map

package/dist/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,OAAO,SAAU,SAAQ,KAAK;IACI,MAAM;IAA5C,YAAY,OAAe,EAAW,MAAmB;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;sBADqB,MAAM;QAE1C,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAgBD,SAAS,YAAY,CAAC,YAAoB;IACxC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;IAC3D,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAClC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAI,OAAkC;IACzE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC5C,MAAM,QAAQ,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAC3C,IAAI,KAAK,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IAC5C,SAAS,CAAC;QACR,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;YAAE,MAAM,IAAI,SAAS,CAAC,uBAAuB,EAAE,SAAS,CAAC,CAAC;QACrF,MAAM,SAAS,GAAG,QAAQ,GAAG,GAAG,EAAE,CAAC;QACnC,IAAI,SAAS,IAAI,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,kEAAkE,EAAE,SAAS,CAAC,CAAC;QACvH,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;QACxC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACzD,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;YAAE,MAAM,IAAI,SAAS,CAAC,uBAAuB,EAAE,SAAS,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QAClF,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,SAAS,CAAC,sCAAsC,EAAE,kBAAkB,CAAC,CAAC;IAC5G,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@sinecloud/api-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Shared polling and terminal-status contracts for the first-party Sine Cloud clients.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fei-bai-inc/sinecloud.git",
+    "directory": "packages/api-client"
+  },
+  "homepage": "https://docs.sinecloud.dev/sdk",
+  "bugs": {
+    "url": "https://github.com/fei-bai-inc/sinecloud/issues"
+  },
+  "keywords": [
+    "sinecloud",
+    "sdk",
+    "polling",
+    "task"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }