@hlix/sdk 0.2.0 → 0.3.0

package/dist/observe.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A worker's live coder output, as frames.
+ *
+ * `GET /v1/api/projects/:projectId/agents/:agentId/observe` is NOT in
+ * `openapi.json`, so this type is written by hand rather than generated. That
+ * is a deliberate, narrow exception and it is the reason `parseObserveFrame`
+ * exists: a hand-written type is a claim about somebody else's route, so the
+ * parser treats the wire as untrusted and returns `null` for anything it does
+ * not recognise instead of casting. When the route is added to the contract,
+ * delete this file and take the generated type.
+ *
+ * The vocabulary is the backend's `toWorkerObserveFrame`
+ * (`apps/backend/src/routes/agent-turn-observe.ts`) plus `coderFrameToSse`
+ * (`engine/sandbox/coder-stream.ts`). Both project onto the SAME shape on
+ * purpose — the native `hlix` coder streams as a Mastra durable run and an
+ * external ACP coder streams as driver frames, and a watcher should not have
+ * to know which one it got.
+ */
+export type ObserveFrame = 
+/** No task yet, or its latest task is not being coded. The stream then ends. */
+{
+    type: "idle";
+}
+/** A live turn was found. `runId` is the durable run, or the task's own id. */
+ | {
+    type: "active";
+    runId?: string;
+} | {
+    type: "on_chat_model_stream";
+    delta: string;
+} | {
+    type: "reasoning";
+    delta: string;
+} | {
+    type: "on_tool_start";
+    name: string;
+    input?: unknown;
+} | {
+    type: "on_tool_end";
+    name: string;
+    output?: unknown;
+} | {
+    type: "done";
+} | {
+    type: "error";
+    message: string;
+};
+/**
+ * One SSE `data:` payload → a frame, or `null` when it is not one.
+ *
+ * Unparseable JSON, a missing `type`, and a `type` this client has no branch
+ * for all return `null`. A caller iterating frames therefore never sees a
+ * half-built object, and a frame added to the route later is ignored rather
+ * than rendered as `undefined`.
+ */
+export declare function parseObserveFrame(data: string): ObserveFrame | null;
+/** Frames after which no more will arrive, so a reader can stop rather than wait. */
+export declare const isTerminalObserveFrame: (frame: ObserveFrame) => boolean;

package/dist/retry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Bounded retry — and, far more importantly, the refusal to retry.
+ *
+ * THE RULE THAT MUST NOT BEND: a non-idempotent request is never retried, ever,
+ * under any status, including a network failure where the SDK cannot know
+ * whether the server acted. `POST /v1/api/cycles/:id/execute` dispatches
+ * paid coder runs; `POST /v1/api/tasks` creates work. A retry that "helpfully"
+ * recovers a dropped response duplicates that work, which is precisely the
+ * hazard durable attempt identity and the reconciler exist to eliminate. An SDK
+ * that reintroduces it at the client layer defeats both.
+ *
+ * So the set below is the RFC 9110 idempotent set, and it is an allowlist, not
+ * a denylist: a verb nobody thought about is not retried.
+ *
+ * A note on DELETE, which is idempotent by the RFC and still has a sharp edge:
+ * retrying one whose response was lost can answer 404 the second time, so a
+ * caller may see "not found" for a delete that in fact succeeded. That is a
+ * reporting artefact rather than duplicated work — the server state is what the
+ * caller asked for either way — which is why it stays in the set. It is called
+ * out because a reader deserves to know it was considered rather than missed.
+ */
+/** RFC 9110 §9.2.2. POST and PATCH are absent on purpose. */
+export declare const IDEMPOTENT_METHODS: ReadonlySet<string>;
+export declare function isIdempotent(method: string): boolean;
+export declare function isRetryableStatus(status: number): boolean;
+export interface RetryPolicy {
+    /** Total attempts including the first. 1 disables retry entirely. */
+    attempts: number;
+    /** First backoff step in ms; doubles per attempt. */
+    baseDelayMs: number;
+    /** Ceiling for a single wait, before jitter. */
+    maxDelayMs: number;
+}
+export declare const DEFAULT_RETRY: RetryPolicy;
+/**
+ * Exponential backoff with full jitter, honouring `Retry-After` when the
+ * server stated one. Jitter matters under load: without it, every client that
+ * saw the same 503 returns in the same millisecond.
+ */
+export declare function backoffDelayMs(attempt: number, policy: RetryPolicy, retryAfterSeconds: number | null, random?: () => number): number;
+/** Whether another attempt is permitted. The verb check comes first. */
+export declare function shouldRetry(input: {
+    method: string;
+    attempt: number;
+    policy: RetryPolicy;
+    status: number | null;
+}): boolean;

package/dist/revision-watch.d.ts

@@ -0,0 +1,29 @@
+export type RevisionWatchFrame = 
+/** Listening. Read the head now: nothing that moved before this is replayed. */
+{
+    kind: "ready";
+}
+/** The revision head advanced to this generation. */
+ | {
+    kind: "head";
+    revisionId: string;
+    generation: number;
+}
+/** The Coding Workspace's files changed; a head read turns that into a revision. */
+ | {
+    kind: "workspace";
+};
+export declare function parseRevisionWatchFrame(data: string): RevisionWatchFrame | null;
+/**
+ * A refusal the server will repeat however often it is asked: a bad credential,
+ * a project out of reach, a repo-backed project this sync does not serve. Only
+ * those end the watch — a dropped connection, a restart or a 5xx reconnects,
+ * because a mirror left deaf by a deploy is the failure this exists to prevent.
+ */
+export declare function isPermanentWatchFailure(error: unknown): boolean;
+export declare const WATCH_RECONNECT: {
+    firstDelayMs: number;
+    maxDelayMs: number;
+};
+/** Resolves after `ms`, or at once when `signal` aborts. */
+export declare function pause(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/streaming.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Server-Sent Events, parsed to the WHATWG spec.
+ *
+ * Streaming is this product's defining behaviour — task status, cycle
+ * lifecycle, live agent output — so the SDK consumes it directly rather than
+ * handing back a raw body and wishing the caller luck. `EventSource` is not an
+ * option: it cannot send an `x-api-key` header or a cross-origin cookie, and it
+ * only speaks GET.
+ *
+ * Spec details that are easy to get wrong and are handled here:
+ *   - a field line is `name: value`, and exactly ONE leading space of the value
+ *     is stripped (`data:  x` is ` x`);
+ *   - multiple `data:` lines join with "\n";
+ *   - a line starting with `:` is a comment — servers use it as a heartbeat;
+ *   - CRLF, CR and LF are all line terminators;
+ *   - an event with an EMPTY data buffer is not dispatched. That is the spec,
+ *     and it means the backend's `event: keepalive` frames (which carry no
+ *     data) never surface as events. They still do their job — they keep the
+ *     connection warm — but a caller that wants a liveness signal must use a
+ *     timeout, not wait for a keepalive it will never see.
+ */
+export interface SseEvent {
+    /** The `event:` field, or null when the server sent none. */
+    event: string | null;
+    /** Joined `data:` lines, newline-separated. Never empty when dispatched. */
+    data: string;
+    /** The `id:` field, or null. */
+    id: string | null;
+    /** The `retry:` field in ms, or null. */
+    retry: number | null;
+}
+/** Parse a byte stream of `text/event-stream` into events. */
+export declare function parseSseStream(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseEvent>;

package/dist/test-schema-guard.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Turns "the database is not migrated" into an instruction instead of a
+ * confusing red.
+ *
+ * TEST-ONLY. It is not exported from `index.ts` and is not a tsup entry, so it
+ * never reaches the published bundle.
+ *
+ * Why it exists: these tests preload the backend's `pool-lifecycle.ts` for its
+ * pool discipline, and that preload also carries a default — when
+ * `DATABASE_URL` is unset it redirects to the `hlix` database. That default is
+ * correct for `apps/backend`, where `hlix` IS the dev database, and wrong here.
+ * A developer running `bun run --filter '@hlix/sdk' test` with no env set then
+ * silently drives a database that may be several migrations behind, and the
+ * failures read as SDK bugs rather than as a stale schema. That is how this was
+ * first hit: two failures on a merged tree that were nothing to do with the
+ * change under review.
+ *
+ * A README line would not have prevented it. This does, because it runs.
+ */
+/**
+ * Run test setup, and if it fails because the schema is behind, rethrow with
+ * the command that fixes it and the URL it must be run against.
+ *
+ * Any other failure propagates untouched — a guard that swallowed real errors
+ * would be worse than the confusion it removes.
+ */
+export declare function withSchemaGuard<T>(setup: () => Promise<T>): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hlix/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "description": "Typed client for the hlix API — auth, organization scoping, typed errors, SSE streaming, and bounded retry on idempotent verbs only.",
   "keywords": [
@@ -38,17 +38,17 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
-    "test": "bun test --isolate",
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --external openapi-fetch && bunx tsc -p tsconfig.json --emitDeclarationOnly --outDir dist && bun run scripts/fix-dts.ts",
+    "test": "bun test --isolate src --path-ignore-patterns \"**/*.integration.test.ts\" --timeout 20000",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run typecheck && bun run build && bun test --isolate"
+    "prepublishOnly": "bun run typecheck && bun run build && bun run test",
+    "test:integration": "NODE_ENV=test bun run ../../apps/backend/scripts/with-aimock.ts -- bun run ../../apps/backend/scripts/with-test-db.ts -- bun test --isolate --preload ../../apps/backend/test/helpers/pool-lifecycle.ts --timeout 60000 .integration.test.ts"
   },
   "dependencies": {
     "openapi-fetch": "^0.17.0"
   },
   "devDependencies": {
     "@hlix/api-client": "workspace:*",
-    "tsup": "^8.5.0",
-    "typescript": "^5.7.2"
+    "typescript": "^7.0.2"
   }
 }