tila-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,464 @@
+import { TilaProjectConfig } from './config';
+import { z } from 'zod';
+import { EntityResponse, EntityDetailResponse, EntityListResponse, ArchiveSuccessResponse, CreateEntityRelationshipResponse, EntityArtifactReferenceListResponse, AcquireSuccessResponse, RenewSuccessResponse, ReleaseSuccessResponse, StateListResponse, StateResponse, ArtifactPutResponse, ArtifactListResponse, ArtifactSearchResponse, ArtifactGrepResponse, ArtifactRelationshipOkResponse, ArtifactRelationshipListResponse, TokenIssueResponse, TokenRevokeResponse, TokenListResponse, JournalResponse, PresenceHeartbeatSuccessResponse, PresenceListResponse, PresenceAllListResponse, RecordCreateRequest, RecordMutateResponse, RecordSetRequest, RecordGetResponse, RecordPatchRequest, RecordArchiveRequest, RecordUnarchiveRequest, RecordHistoryResponse, RecordListResponse, RecordTypesResponse, InstantiateTemplateRequest, InstantiateTemplateResponse, SummaryResponse, UnifiedSearchResponse } from './api';
+export { AcquireSuccessResponse, ArtifactGrepResponse, ArtifactListResponse, ArtifactPutResponse, ArtifactSearchResponse, EntityDetailResponse, EntityListResponse, EntityResponse, InstantiateTemplateRequest, InstantiateTemplateResponse, JournalResponse, PresenceAllListResponse, PresenceListResponse, RecordArchiveRequest, RecordCreateRequest, RecordGetResponse, RecordHistoryItem, RecordHistoryResponse, RecordItem, RecordListItem, RecordListResponse, RecordMutateResponse, RecordPatchRequest, RecordSetRequest, RecordTypesResponse, RecordUnarchiveRequest, ReleaseSuccessResponse, RenewSuccessResponse, SummaryResponse, TokenIssueResponse, TokenListResponse, TokenRevokeResponse, UnifiedSearchQuery, UnifiedSearchResponse, UnifiedSearchResult } from './api';
+import { ClaimMode } from './claim';
+import { ArtifactPointer } from './artifact';
+import { InboxResponse, SendSignalRequest, SendSignalResponse, AckSignalResponse } from './signal';
+export { AckSignalResponse, InboxResponse, SendSignalRequest, SendSignalResponse } from './signal';
+import { GateListResponse, CreateGateRequest, GateResponse, ResolveGateRequest } from './gate';
+export { CreateGateRequest, GateListResponse, GateResponse, ResolveGateRequest } from './gate';
+
+interface ClientOptions {
+    baseUrl: string;
+    token: string;
+    validate?: boolean;
+    /** Request timeout in milliseconds. Default: 30000 (30s). */
+    timeoutMs?: number;
+    /** Extra headers to include on every request. Overrides the default X-Tila-Source header if provided. */
+    extraHeaders?: Record<string, string>;
+}
+declare class TilaClient {
+    private baseUrl;
+    private token;
+    private validate;
+    private timeoutMs;
+    private extraHeaders;
+    constructor(opts: ClientOptions);
+    /**
+     * Creates an AbortSignal that fires after this.timeoutMs.
+     * Uses AbortSignal.timeout() when available (Node 18.8+, Bun 0.5+, browsers),
+     * falls back to manual setTimeout + AbortController for older runtimes.
+     *
+     * Note: Cloudflare Workers has supported AbortSignal.timeout() since 2023;
+     * the fallback branch will never execute there.
+     */
+    private createAbortSignal;
+    static fromConfig(config: TilaProjectConfig, token: string): TilaClient;
+    request<T>(method: string, path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, string | undefined>;
+        schema?: z.ZodType<T>;
+        validate?: boolean;
+    }): Promise<T>;
+    get<T>(path: string, opts?: {
+        schema?: z.ZodType<T>;
+        query?: Record<string, string | undefined>;
+        validate?: boolean;
+    }): Promise<T>;
+    post<T>(path: string, body: unknown, opts?: {
+        schema?: z.ZodType<T>;
+        validate?: boolean;
+    }): Promise<T>;
+    put<T>(path: string, body: unknown, opts?: {
+        schema?: z.ZodType<T>;
+        validate?: boolean;
+    }): Promise<T>;
+    patch<T>(path: string, body: unknown, opts?: {
+        schema?: z.ZodType<T>;
+        validate?: boolean;
+    }): Promise<T>;
+    delete<T>(path: string, opts?: {
+        schema?: z.ZodType<T>;
+        validate?: boolean;
+    }): Promise<T>;
+    requestRaw(method: string, path: string, opts?: {
+        query?: Record<string, string | undefined>;
+    }): Promise<Response>;
+    postFormData<T>(path: string, formData: FormData, opts?: {
+        schema?: z.ZodType<T>;
+        validate?: boolean;
+    }): Promise<T>;
+    private throwApiError;
+}
+declare class TilaApiError extends Error {
+    status: number;
+    code: string;
+    retryable: boolean;
+    constructor(status: number, code: string, message: string, retryable: boolean);
+}
+declare function isTilaApiError(err: unknown): err is TilaApiError;
+declare function exchangeGitHubToken(baseUrl: string, projectId: string, githubToken: string): Promise<{
+    sessionToken: string;
+    expiresAt: number;
+    permission: string;
+}>;
+
+interface RetryOptions {
+    /** Maximum number of retry attempts after the first failure. Default: 3. */
+    maxRetries?: number;
+    /** Base delay in milliseconds for exponential backoff. Default: 200. */
+    baseDelayMs?: number;
+    /** Maximum delay cap in milliseconds. Default: 30000. */
+    maxDelayMs?: number;
+    /** Whether to apply full jitter to the delay. Default: true. */
+    jitter?: boolean;
+}
+/**
+ * Retry wrapper with exponential backoff and full jitter.
+ *
+ * Follows the AWS "Full Jitter" pattern:
+ *   sleep = random(0, min(cap, base * 2^attempt))
+ *
+ * Hard stop: if the thrown error is a TilaApiError with retryable === false,
+ * it is re-thrown immediately without waiting or counting against maxRetries.
+ * This is unconditional -- callers cannot override it.
+ *
+ * Non-TilaApiError errors (network errors, timeouts, TypeErrors) are always
+ * retried up to maxRetries.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+
+/**
+ * Typed error code constants for all tila API error responses.
+ *
+ * Keys are normalized identifiers. Values are the exact wire-format strings
+ * returned by the worker and DO layers.
+ *
+ * NOTE: The codebase uses two conventions for error codes:
+ * - SCREAMING_SNAKE_CASE for worker/auth-layer codes ("UNAUTHORIZED", "SESSION_EXPIRED")
+ * - kebab-case for DO-layer codes ("stale-fence", "not-found")
+ * TILA_ERRORS preserves both conventions in its values. The _UPPER suffix on
+ * VALIDATION_ERROR_UPPER disambiguates the two distinct wire values for
+ * "validation error" used in different layers.
+ */
+declare const TILA_ERRORS: {
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly PROJECT_MISMATCH: "PROJECT_MISMATCH";
+    readonly CSRF_MISSING_ORIGIN: "CSRF_MISSING_ORIGIN";
+    readonly CSRF_ORIGIN_MISMATCH: "CSRF_ORIGIN_MISMATCH";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly DO_UNREACHABLE: "do-unreachable";
+    readonly REPO_NOT_ALLOWED: "REPO_NOT_ALLOWED";
+    readonly GITHUB_AUTH_FAILED: "GITHUB_AUTH_FAILED";
+    readonly HMAC_NOT_CONFIGURED: "HMAC_NOT_CONFIGURED";
+    readonly TOKEN_NAME_CONFLICT: "TOKEN_NAME_CONFLICT";
+    readonly TOKEN_AUTHZ_DENIED: "TOKEN_AUTHZ_DENIED";
+    readonly TOKEN_NOT_FOUND: "TOKEN_NOT_FOUND";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly STALE_FENCE: "stale-fence";
+    readonly NOT_FOUND: "not-found";
+    readonly GATE_ALREADY_SETTLED: "gate-already-settled";
+    readonly NO_FENCE: "no-fence";
+    readonly INTERNAL: "internal";
+    readonly CONSTRAINT_VIOLATION: "constraint-violation";
+    readonly IDEMPOTENCY_KEY_CONFLICT: "idempotency-key-conflict";
+    readonly VALIDATION_ERROR_DO: "validation-error";
+    readonly ALREADY_HELD: "already-held";
+    readonly RENEW_FAILED: "renew-failed";
+    readonly BAD_REQUEST: "bad-request";
+    readonly MISSING_QUERY: "missing-query";
+    readonly INVALID_QUERY: "invalid-query";
+    readonly INVALID_SLOT: "invalid-slot";
+    readonly INVALID_RELATIONSHIP_TYPE: "invalid-relationship-type";
+    readonly UNKNOWN: "UNKNOWN";
+};
+type TilaErrorCode = (typeof TILA_ERRORS)[keyof typeof TILA_ERRORS];
+
+/**
+ * Creates task API methods using the canonical /tasks public path.
+ */
+declare function createTaskMethods(client: TilaClient, projectId: string): {
+    create(id: string, type: string, data?: Record<string, unknown>): Promise<EntityResponse>;
+    get(id: string): Promise<EntityDetailResponse>;
+    list(query?: {
+        type?: string;
+        status?: string;
+        limit?: string;
+        cursor?: string;
+    }): Promise<EntityListResponse>;
+    update(id: string, data: Record<string, unknown>, fence: number): Promise<EntityResponse>;
+    archive(id: string, fence: number): Promise<ArchiveSuccessResponse>;
+    addRelationship(fromId: string, toId: string, type: string): Promise<CreateEntityRelationshipResponse>;
+    addArtifactRef(entityId: string, artifactKey: string, slot: string, metadata?: Record<string, unknown>): Promise<{
+        ok: true;
+    }>;
+    listArtifactRefs(entityId: string): Promise<EntityArtifactReferenceListResponse>;
+};
+/**
+ * @deprecated Use createTaskMethods instead.
+ */
+declare function createEntityMethods(client: TilaClient, projectId: string): {
+    create(id: string, type: string, data?: Record<string, unknown>): Promise<EntityResponse>;
+    get(id: string): Promise<EntityDetailResponse>;
+    list(query?: {
+        type?: string;
+        status?: string;
+        limit?: string;
+        cursor?: string;
+    }): Promise<EntityListResponse>;
+    update(id: string, data: Record<string, unknown>, fence: number): Promise<EntityResponse>;
+    archive(id: string, fence: number): Promise<ArchiveSuccessResponse>;
+    addRelationship(fromId: string, toId: string, type: string): Promise<CreateEntityRelationshipResponse>;
+    addArtifactRef(entityId: string, artifactKey: string, slot: string, metadata?: Record<string, unknown>): Promise<{
+        ok: true;
+    }>;
+    listArtifactRefs(entityId: string): Promise<EntityArtifactReferenceListResponse>;
+};
+/**
+ * @deprecated Use createTaskMethods instead.
+ */
+declare function createWorkUnitMethods(client: TilaClient, projectId: string): {
+    create(id: string, type: string, data?: Record<string, unknown>): Promise<EntityResponse>;
+    get(id: string): Promise<EntityDetailResponse>;
+    list(query?: {
+        type?: string;
+        status?: string;
+        limit?: string;
+        cursor?: string;
+    }): Promise<EntityListResponse>;
+    update(id: string, data: Record<string, unknown>, fence: number): Promise<EntityResponse>;
+    archive(id: string, fence: number): Promise<ArchiveSuccessResponse>;
+    addRelationship(fromId: string, toId: string, type: string): Promise<CreateEntityRelationshipResponse>;
+    addArtifactRef(entityId: string, artifactKey: string, slot: string, metadata?: Record<string, unknown>): Promise<{
+        ok: true;
+    }>;
+    listArtifactRefs(entityId: string): Promise<EntityArtifactReferenceListResponse>;
+};
+
+declare function createClaimMethods(client: TilaClient, projectId: string): {
+    acquire(resource: string, mode: ClaimMode, ttlMs: number, opts?: {
+        metadata?: Record<string, unknown>;
+        idempotency_key?: string;
+    }): Promise<AcquireSuccessResponse>;
+    renew(resource: string, fence: number, ttlMs: number): Promise<RenewSuccessResponse>;
+    release(resource: string, fence: number): Promise<ReleaseSuccessResponse>;
+    list(): Promise<StateListResponse>;
+    get(resource: string): Promise<StateResponse>;
+};
+
+interface ArtifactUploadOpts {
+    kind: string;
+    resource?: string;
+    fence?: number;
+    mimeType?: string;
+    flavor?: string;
+}
+declare function createArtifactMethods(client: TilaClient, projectId: string): {
+    upload: {
+        (file: File | Blob, opts: ArtifactUploadOpts): Promise<ArtifactPutResponse>;
+        (stream: ReadableStream, opts: ArtifactUploadOpts & {
+            mimeType: string;
+        }): Promise<ArtifactPutResponse>;
+    };
+    download(key: string): Promise<{
+        body: ReadableStream;
+        contentType: string;
+        contentLength: number | null;
+    }>;
+    list(query?: {
+        resource?: string;
+        kind?: string;
+        limit?: string;
+    }): Promise<ArtifactListResponse>;
+    search(q: string, opts?: {
+        kind?: string;
+        resource?: string;
+        limit?: string;
+    }): Promise<ArtifactSearchResponse>;
+    grep(pattern: string, opts?: {
+        kind?: string;
+        resource?: string;
+        regex?: boolean;
+        limit?: number;
+    }): Promise<ArtifactGrepResponse>;
+    addRelationship(fromKey: string, toKeyOrUri: string, type: string, metadata?: Record<string, unknown>): Promise<ArtifactRelationshipOkResponse>;
+    listRelationships(key: string): Promise<ArtifactRelationshipListResponse>;
+    getLatest(kind: string, resource: string): Promise<ArtifactPointer | null>;
+    writeText(content: string, opts: {
+        kind: string;
+        mimeType?: string;
+        resource?: string;
+        fence?: number;
+    }): Promise<ArtifactPutResponse>;
+    readText(key: string): Promise<{
+        content: string;
+        mimeType: string;
+    }>;
+};
+
+declare function createTokenMethods(client: TilaClient): {
+    issue(name: string, note?: string): Promise<TokenIssueResponse>;
+    revoke(name: string): Promise<TokenRevokeResponse>;
+    list(): Promise<TokenListResponse>;
+};
+
+declare function createJournalMethods(client: TilaClient, projectId: string): {
+    query(opts?: {
+        entity_id?: string;
+        event_kind?: string;
+        limit?: string;
+        cursor?: string;
+    }): Promise<JournalResponse>;
+};
+
+declare function createPresenceMethods(client: TilaClient, projectId: string): {
+    heartbeat(machine: string, ttlMs?: number): Promise<PresenceHeartbeatSuccessResponse>;
+    list(): Promise<PresenceListResponse>;
+    /**
+     * List all presence records across all machines, including whether each is active.
+     * Hits GET /projects/:projectId/presence/all
+     */
+    listAll(): Promise<PresenceAllListResponse>;
+};
+
+declare function createRecordMethods(client: TilaClient, projectId: string): {
+    create(type: string, req: RecordCreateRequest): Promise<RecordMutateResponse>;
+    set(type: string, key: string, req: RecordSetRequest): Promise<RecordMutateResponse>;
+    get(type: string, key: string): Promise<RecordGetResponse>;
+    patch(type: string, key: string, req: RecordPatchRequest): Promise<RecordMutateResponse>;
+    archive(type: string, key: string, req: RecordArchiveRequest): Promise<RecordMutateResponse>;
+    unarchive(type: string, key: string, req: RecordUnarchiveRequest): Promise<RecordMutateResponse>;
+    history(type: string, key: string, opts?: {
+        limit?: number;
+        values?: boolean;
+    }): Promise<RecordHistoryResponse>;
+    list(type: string, query?: {
+        tag?: string;
+        filter?: string;
+        "include-archived"?: string;
+        limit?: string;
+    }): Promise<RecordListResponse>;
+    types(): Promise<RecordTypesResponse>;
+    typesInUse(): Promise<RecordTypesResponse>;
+};
+
+declare function createSchemaMethods(client: TilaClient, projectId: string): {
+    get(): Promise<{
+        ok: true;
+        schema: unknown;
+        version: number;
+    }>;
+    apply(schema: unknown, strategy?: string): Promise<{
+        ok: true;
+        version: number;
+        diff: unknown;
+    }>;
+    history(opts?: {
+        limit?: string;
+    }): Promise<{
+        ok: true;
+        entries: unknown[];
+    }>;
+};
+
+declare function createSignalMethods(client: TilaClient, projectId: string): {
+    /** Fetch the signal inbox for the current token. GET /projects/:id/signals */
+    inbox(): Promise<InboxResponse>;
+    /** Send a signal to a target. POST /projects/:id/signals/send */
+    send(req: SendSignalRequest): Promise<SendSignalResponse>;
+    /** Acknowledge a signal. POST /projects/:id/signals/:signalId/ack */
+    ack(signalId: string): Promise<AckSignalResponse>;
+};
+
+declare function createGateMethods(client: TilaClient, projectId: string): {
+    /** List gates with optional filters. GET /projects/:id/gates */
+    list(query?: {
+        resource?: string;
+        status?: string;
+        limit?: string;
+    }): Promise<GateListResponse>;
+    /** Create a new gate. POST /projects/:id/gates */
+    create(req: CreateGateRequest): Promise<GateResponse>;
+    /** Resolve a gate. POST /projects/:id/gates/:gateId/resolve */
+    resolve(gateId: string, req?: ResolveGateRequest): Promise<GateResponse>;
+    /** Delete a gate. DELETE /projects/:id/gates/:gateId */
+    remove(gateId: string): Promise<{
+        ok: true;
+    }>;
+};
+
+declare function createTemplateMethods(client: TilaClient, projectId: string): {
+    /** Instantiate an entity template. POST /projects/:id/templates/instantiate */
+    instantiate(req: InstantiateTemplateRequest): Promise<InstantiateTemplateResponse>;
+    /** List available templates from the project schema. GET /projects/:id/templates */
+    list(): Promise<{
+        ok: true;
+        templates: Array<{
+            name: string;
+            type: string;
+            description: string | null;
+            variables: string[];
+        }>;
+    }>;
+};
+
+interface IndexCreateOpts {
+    kind?: string;
+    resource?: string;
+    mimeType?: string;
+    flavor?: string;
+}
+declare function createIndexMethods(client: TilaClient, projectId: string): {
+    /**
+     * Create an index artifact. Uploads file content with flavor=index.
+     * Returns the artifact key and byte count.
+     */
+    create(input: File | Blob, opts?: IndexCreateOpts): Promise<ArtifactPutResponse>;
+    /**
+     * Add an entry artifact to an index. Records the relationship
+     * entry_key -> index_key with type "entry-of".
+     */
+    addEntry(entryKey: string, indexKey: string): Promise<ArtifactRelationshipOkResponse>;
+    /**
+     * List relationships FROM the given index key. Note: this returns
+     * forward relationships (what the index points to), not a reverse
+     * lookup of entries pointing to this index. The HTTP API does not
+     * expose a reverse-lookup endpoint; for that, use the CLI's
+     * `tila index list-entries` which queries ops-sqlite directly.
+     */
+    listEntries(indexKey: string): Promise<ArtifactRelationshipListResponse>;
+};
+
+declare function createSummaryMethods(client: TilaClient, projectId: string): {
+    /** Get project summary. GET /projects/:id/summary */
+    get(): Promise<SummaryResponse>;
+};
+
+declare function createSearchMethods(client: TilaClient, projectId: string): {
+    search(q: string, opts?: {
+        limit?: number;
+    }): Promise<UnifiedSearchResponse>;
+};
+
+type ErrorListener = (err: TilaApiError | Error) => void;
+interface ClaimHandleOptions {
+    client: TilaClient;
+    projectId: string;
+    resource: string;
+    fence: number;
+    expiresAt: number;
+}
+declare class ClaimHandle {
+    readonly resource: string;
+    readonly fence: number;
+    readonly expiresAt: number;
+    private client;
+    private projectId;
+    private errorListeners;
+    constructor(opts: ClaimHandleOptions);
+    on(event: "error", listener: ErrorListener): void;
+    private emitError;
+    updateEntity(id: string, data: Record<string, unknown>): Promise<EntityResponse>;
+    uploadArtifact(file: File | Blob, opts: Omit<ArtifactUploadOpts, "fence">): Promise<ArtifactPutResponse>;
+    uploadArtifact(stream: ReadableStream, opts: Omit<ArtifactUploadOpts, "fence"> & {
+        mimeType: string;
+    }): Promise<ArtifactPutResponse>;
+    addArtifactRef(entityId: string, artifactKey: string, slot: string): Promise<void>;
+    startHeartbeat(ttlMs: number, opts?: {
+        intervalMs?: number;
+    }): {
+        stop(): void;
+    };
+    onClaimExpiring(leadMs: number, callback: () => void): {
+        stop(): void;
+    };
+    /** @internal Release the claim. Errors are swallowed by withClaim's finally. */
+    _release(): Promise<void>;
+}
+declare function withClaim<T>(client: TilaClient, projectId: string, resource: string, mode: ClaimMode, ttlMs: number, callback: (handle: ClaimHandle) => Promise<T>): Promise<T>;
+
+export { type ArtifactUploadOpts, ClaimHandle, type ClaimHandleOptions, type ClientOptions, type IndexCreateOpts, type RetryOptions, TILA_ERRORS, TilaApiError, TilaClient, type TilaErrorCode, createArtifactMethods, createClaimMethods, createEntityMethods, createGateMethods, createIndexMethods, createJournalMethods, createPresenceMethods, createRecordMethods, createSchemaMethods, createSearchMethods, createSignalMethods, createSummaryMethods, createTaskMethods, createTemplateMethods, createTokenMethods, createWorkUnitMethods, exchangeGitHubToken, isTilaApiError, withClaim, withRetry };