@hlix/sdk 0.2.0 → 0.3.0

package/dist/api-client/src/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@hlix/api-client` — the generated, typed transport for the hlix API.
+ *
+ * Derived from `apps/backend/openapi.json`, which is itself emitted from the
+ * Zod validators the routes run. One schema, all the way from request
+ * validation to this package's types, so a client cannot be typed against a
+ * shape the server does not accept.
+ *
+ * Transport-only. See `client.ts` for what that excludes and why.
+ */
+export { createHlixClient } from "./client";
+export type { HlixClient, HlixClientOptions } from "./client";
+export type { components, operations, paths } from "./generated/schema";

package/dist/auth.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Credentials and tenancy — the two things every caller would otherwise
+ * reimplement, and the two the transport layer deliberately refuses to own.
+ *
+ * THREE credential kinds, because the API really does accept three:
+ *
+ *   - `apiKey`  → `x-api-key`. The documented scheme for programmatic callers.
+ *   - `session` → the better-auth session cookie, which is what a browser
+ *     already holds. Browser-login exchange can mint a scoped API key for a CLI.
+ *   - `bearer`  → `Authorization: Bearer <session token>`, the same session
+ *     as a bare token (better-auth's bearer plugin). What the desktop app holds
+ *     and hands to the `hlix` sidecar it runs on the person's machine.
+ *
+ * The backend verifies API keys in its explicit API middleware rather than
+ * enabling Better Auth's session emulation for keys. A key authenticates its
+ * owner but carries no active workspace; programmatic callers should always
+ * provide `organizationId`.
+ */
+export type HlixCredential = {
+    readonly kind: "apiKey";
+    readonly apiKey: string;
+} | {
+    readonly kind: "session";
+    readonly cookie: string;
+} | {
+    readonly kind: "bearer";
+    readonly token: string;
+};
+export declare const apiKeyCredential: (apiKey: string) => HlixCredential;
+export declare const sessionCredential: (cookie: string) => HlixCredential;
+export declare const bearerCredential: (token: string) => HlixCredential;
+/** The credential header pair. Never logged — callers print SDK errors. */
+export declare function credentialHeaders(credential: HlixCredential): Record<string, string>;
+/**
+ * Tenant selection. Omitted, the server falls back to the session's active
+ * organization — which is a real default for a browser, and a trap for a
+ * script that assumes it knows which workspace it just wrote to. The SDK
+ * therefore sends the header whenever it was given one and never invents one.
+ */
+export declare function organizationHeaders(organizationId: string | undefined): Record<string, string>;
+export declare function authHeaders(credential: HlixCredential, organizationId: string | undefined): Record<string, string>;

package/dist/errors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Typed errors, so a caller branches on a denial instead of string-matching.
+ *
+ * Every class carries the HTTP status and the server's parsed body. The shapes
+ * come from the published contract (`apps/backend/openapi.json`): a handled
+ * failure is `{ error: string }` (`ApiError`), and a body that fails schema
+ * validation is `{ success: false, error: { name, message } }`
+ * (`ValidationError`), where `message` is a JSON-encoded array of issues rather
+ * than a sentence. `HlixValidationError` parses that for you — printing it raw
+ * is what the contract warns against.
+ */
+export interface HlixErrorInit {
+    status: number;
+    body: unknown;
+    /** `x-request-id`, when the response carried one — the handle for support. */
+    requestId?: string | null;
+    method: string;
+    url: string;
+}
+export declare class HlixError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly requestId: string | null;
+    readonly method: string;
+    readonly url: string;
+    constructor(message: string, init: HlixErrorInit);
+}
+/** 400 — the request body did not satisfy the route's schema. */
+export declare class HlixValidationError extends HlixError {
+    /** The decoded `ZodIssue[]`; empty when the server sent a plain message. */
+    readonly issues: unknown[];
+    constructor(message: string, init: HlixErrorInit, issues: unknown[]);
+}
+/** 400 that is not a schema failure — e.g. no active organization. */
+export declare class HlixBadRequestError extends HlixError {
+}
+/** 401 — no valid credential. */
+export declare class HlixAuthenticationError extends HlixError {
+}
+/** 403 — authenticated, but not permitted. */
+export declare class HlixPermissionError extends HlixError {
+}
+/**
+ * 404 — absent, OR present and deliberately hidden. The API answers 404 rather
+ * than 403 for a resource the caller was never granted, so this does NOT mean
+ * "does not exist".
+ */
+export declare class HlixNotFoundError extends HlixError {
+}
+/** 409 — the request conflicts with current state. */
+export declare class HlixConflictError extends HlixError {
+}
+/** 429 — rate limited. `retryAfter` is seconds, when the server said. */
+export declare class HlixRateLimitError extends HlixError {
+    readonly retryAfter: number | null;
+    constructor(message: string, init: HlixErrorInit, retryAfter: number | null);
+}
+/** 501 — a documented, permanent refusal. Never retried. */
+export declare class HlixNotImplementedError extends HlixError {
+}
+/** 5xx. */
+export declare class HlixServerError extends HlixError {
+}
+/** The request never produced a response: DNS, TLS, connection, abort. */
+export declare class HlixTransportError extends Error {
+    readonly method: string;
+    readonly url: string;
+    constructor(message: string, init: {
+        method: string;
+        url: string;
+        cause?: unknown;
+    });
+}
+/** Build the error class that fits a failed response. */
+export declare function errorForResponse(response: Response, body: unknown, request: {
+    method: string;
+    url: string;
+}): HlixError;

package/dist/http.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The retrying transport and the throw-on-failure boundary.
+ *
+ * Retry lives HERE, wrapping `fetch`, rather than around a resource method:
+ * this is the only layer that can see the real HTTP verb, and the verb is what
+ * decides whether a second attempt is permissible at all (see `retry.ts`).
+ * Deciding higher up would mean re-deriving the verb from the method name,
+ * which is exactly the sort of indirection that eventually gets it wrong.
+ */
+import { type HlixError } from "./errors";
+import { type RetryPolicy } from "./retry";
+export type FetchLike = (input: Request) => Promise<Response>;
+export interface RetryingFetchOptions {
+    base: FetchLike;
+    policy: RetryPolicy;
+    /** Injected so tests do not actually sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+}
+/**
+ * `fetch` with bounded retry on idempotent verbs only.
+ *
+ * A non-idempotent request is issued exactly once — including when the
+ * transport throws and the SDK therefore cannot know whether the server acted.
+ * "Might not have happened" is not a licence to do it again.
+ */
+export declare function retryingFetch(options: RetryingFetchOptions): FetchLike;
+/** An openapi-fetch result, narrowed to what the SDK needs. */
+export interface ClientResult<T> {
+    data?: T;
+    error?: unknown;
+    response: Response;
+}
+/**
+ * Return the body or throw a typed error.
+ *
+ * The transport reports failure as a value (`{ error }`); the SDK is allowed
+ * the opinion that a 404 is exceptional, because a caller who wants the value
+ * form can use `raw`.
+ */
+export declare function unwrap<T>(result: ClientResult<T>, request: {
+    method: string;
+    url: string;
+}): T;
+export type { HlixError };