@tinycloud/sdk-services 3.8.0-beta.1 → 3.8.0-beta.18

package/dist/{BaseService-DO7vZ67k.d.ts → BaseService-Ma2MwJAd.d.ts}

@@ -1,4 +1,4 @@
-import { c as IService, I as IServiceContext, S as ServiceSession, f as ServiceError, g as ServiceHeaders, d as FetchRequestInit, e as FetchResponse, h as Result } from './types-DAOyIbXu.js';
+import { c as IService, I as IServiceContext, S as ServiceSession, g as ServiceError, h as ServiceHeaders, d as FetchRequestInit, e as FetchResponse, f as Result } from './types-CSd0RYir.js';
 
 /**
  * Base Service Types

package/dist/{BaseService-D-29xShG.d.cts → BaseService-O0iyuFLk.d.cts}

@@ -1,4 +1,4 @@
-import { c as IService, I as IServiceContext, S as ServiceSession, f as ServiceError, g as ServiceHeaders, d as FetchRequestInit, e as FetchResponse, h as Result } from './types-DAOyIbXu.cjs';
+import { c as IService, I as IServiceContext, S as ServiceSession, g as ServiceError, h as ServiceHeaders, d as FetchRequestInit, e as FetchResponse, f as Result } from './types-CSd0RYir.cjs';
 
 /**
  * Base Service Types

package/dist/IHooksService-4QNODVy6.d.cts

@@ -0,0 +1,120 @@
+import { f as Result } from './types-CSd0RYir.cjs';
+
+type HookServiceName = "kv" | "sql" | "duckdb";
+interface HookSubscription {
+    space: string;
+    service: HookServiceName;
+    pathPrefix?: string;
+    abilities?: string[];
+}
+interface HookWebhookScope {
+    space: string;
+    service: HookServiceName;
+    pathPrefix?: string;
+    abilities?: string[];
+}
+interface HookWebhookRegistration extends HookWebhookScope {
+    callbackUrl: string;
+    secret: string;
+}
+interface HookWebhookRecord extends HookWebhookScope {
+    id: string;
+    subscriberDid?: string;
+    callbackUrl: string;
+    active: boolean;
+    createdAt: string;
+}
+interface HookWebhookListOptions {
+    space?: string;
+    service?: HookServiceName;
+    pathPrefix?: string;
+}
+interface HookWebhookUnregisterOptions {
+    target?: HookWebhookScope;
+}
+interface HookEvent {
+    type: "write";
+    id: string;
+    space: string;
+    service: string;
+    ability: string;
+    path?: string;
+    /** Logical SQL/DuckDB resource; path may identify an encoded physical table. */
+    databasePath?: string;
+    actor: string;
+    epoch: string;
+    eventIndex: number;
+    timestamp: string;
+}
+interface HookStreamEvent {
+    event: string;
+    data: string;
+    id?: string;
+}
+interface SubscribeOptions {
+    ttlSeconds?: number;
+    signal?: AbortSignal;
+    /**
+     * Called once after the server confirms this authorized stream is ready,
+     * initially and after reconnect/renewal. Schedule durable-row reconciliation
+     * here; the callback is not awaited and readiness is never a write event.
+     */
+    onReady?: () => void;
+}
+interface HooksServiceConfig extends Record<string, unknown> {
+    host?: string;
+    /** Shared-stream retry tuning; see {@link HookStreamRetryConfig}. */
+    streamRetry?: HookStreamRetryConfig;
+}
+/**
+ * Retry policy for the shared `/hooks/events` stream. When the stream fails
+ * (network error, 5xx, or an expired/rotated ticket rejected with 401/403)
+ * it is re-opened with exponential backoff: `HOOK_STREAM_RETRY_BASE_DELAY_MS`
+ * (~250 ms) doubling to `HOOK_STREAM_RETRY_MAX_DELAY_MS` (~30 s) with jitter.
+ * The retry streak resets after an event is received or a stream remains open
+ * for at least 5 seconds. Retries stop when no subscribers remain, when the
+ * service is aborted, or when minting the hook ticket is refused (the iterator
+ * throws that typed error instead).
+ */
+interface HookStreamRetryConfig {
+    /**
+     * Delay before retry attempt `attempt` (1-based). Defaults to the jittered
+     * exponential backoff described above. Must return milliseconds.
+     */
+    delay?: (attempt: number) => number;
+    /**
+     * How a retry delay is awaited — the injectable clock. `delayMs` is the
+     * resolved delay for `attempt`; `signal` aborts the wait early when the
+     * subscription set changes or the service stops. Rejecting or throwing is
+     * treated like a completed wait. After a custom wait returns — whether it
+     * fulfilled, rejected or threw — the service still yields one event-loop
+     * turn so a persistently failing stream can never starve the process.
+     * Defaults to an abortable, unref'd `setTimeout`.
+     */
+    wait?: (delayMs: number, attempt: number, signal: AbortSignal) => Promise<void>;
+}
+
+interface IHooksService {
+    /**
+     * Stream hook events until `options.signal` aborts, the SDK signs out or
+     * the session ends, or the consumer stops iterating. Transient stream
+     * failures — network errors, 5xx, and an expired or rotated ticket rejected
+     * by `/hooks/events` (401/403) — are retried internally with backoff and
+     * never reach the iterator.
+     *
+     * The iterator throws when minting the hook ticket is refused. The thrown
+     * plain `ServiceError` carries `meta.status` with the refusing HTTP status,
+     * so `for await` consumers can branch on it. Stream diagnostics contain only
+     * SDK allow-listed identifiers; foreign error messages and causes are not
+     * copied.
+     * `options.onReady` schedules catch-up after each server-confirmed ready
+     * stream, including an unchanged ready stream joined by a late subscriber.
+     * Subscribe/consume before draining stored rows; notifications are not replay.
+     */
+    subscribe(subscriptions: HookSubscription[], options?: SubscribeOptions): AsyncIterable<HookEvent>;
+    register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
+    list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
+    unregister(id: string, options?: HookWebhookUnregisterOptions): Promise<Result<void>>;
+}
+
+export type { HookSubscription as H, IHooksService as I, SubscribeOptions as S, HooksServiceConfig as a, HookEvent as b, HookWebhookRegistration as c, HookWebhookRecord as d, HookWebhookListOptions as e, HookWebhookUnregisterOptions as f, HookServiceName as g, HookStreamEvent as h, HookStreamRetryConfig as i, HookWebhookScope as j };

package/dist/IHooksService-CvTpJbQD.d.ts

@@ -0,0 +1,120 @@
+import { f as Result } from './types-CSd0RYir.js';
+
+type HookServiceName = "kv" | "sql" | "duckdb";
+interface HookSubscription {
+    space: string;
+    service: HookServiceName;
+    pathPrefix?: string;
+    abilities?: string[];
+}
+interface HookWebhookScope {
+    space: string;
+    service: HookServiceName;
+    pathPrefix?: string;
+    abilities?: string[];
+}
+interface HookWebhookRegistration extends HookWebhookScope {
+    callbackUrl: string;
+    secret: string;
+}
+interface HookWebhookRecord extends HookWebhookScope {
+    id: string;
+    subscriberDid?: string;
+    callbackUrl: string;
+    active: boolean;
+    createdAt: string;
+}
+interface HookWebhookListOptions {
+    space?: string;
+    service?: HookServiceName;
+    pathPrefix?: string;
+}
+interface HookWebhookUnregisterOptions {
+    target?: HookWebhookScope;
+}
+interface HookEvent {
+    type: "write";
+    id: string;
+    space: string;
+    service: string;
+    ability: string;
+    path?: string;
+    /** Logical SQL/DuckDB resource; path may identify an encoded physical table. */
+    databasePath?: string;
+    actor: string;
+    epoch: string;
+    eventIndex: number;
+    timestamp: string;
+}
+interface HookStreamEvent {
+    event: string;
+    data: string;
+    id?: string;
+}
+interface SubscribeOptions {
+    ttlSeconds?: number;
+    signal?: AbortSignal;
+    /**
+     * Called once after the server confirms this authorized stream is ready,
+     * initially and after reconnect/renewal. Schedule durable-row reconciliation
+     * here; the callback is not awaited and readiness is never a write event.
+     */
+    onReady?: () => void;
+}
+interface HooksServiceConfig extends Record<string, unknown> {
+    host?: string;
+    /** Shared-stream retry tuning; see {@link HookStreamRetryConfig}. */
+    streamRetry?: HookStreamRetryConfig;
+}
+/**
+ * Retry policy for the shared `/hooks/events` stream. When the stream fails
+ * (network error, 5xx, or an expired/rotated ticket rejected with 401/403)
+ * it is re-opened with exponential backoff: `HOOK_STREAM_RETRY_BASE_DELAY_MS`
+ * (~250 ms) doubling to `HOOK_STREAM_RETRY_MAX_DELAY_MS` (~30 s) with jitter.
+ * The retry streak resets after an event is received or a stream remains open
+ * for at least 5 seconds. Retries stop when no subscribers remain, when the
+ * service is aborted, or when minting the hook ticket is refused (the iterator
+ * throws that typed error instead).
+ */
+interface HookStreamRetryConfig {
+    /**
+     * Delay before retry attempt `attempt` (1-based). Defaults to the jittered
+     * exponential backoff described above. Must return milliseconds.
+     */
+    delay?: (attempt: number) => number;
+    /**
+     * How a retry delay is awaited — the injectable clock. `delayMs` is the
+     * resolved delay for `attempt`; `signal` aborts the wait early when the
+     * subscription set changes or the service stops. Rejecting or throwing is
+     * treated like a completed wait. After a custom wait returns — whether it
+     * fulfilled, rejected or threw — the service still yields one event-loop
+     * turn so a persistently failing stream can never starve the process.
+     * Defaults to an abortable, unref'd `setTimeout`.
+     */
+    wait?: (delayMs: number, attempt: number, signal: AbortSignal) => Promise<void>;
+}
+
+interface IHooksService {
+    /**
+     * Stream hook events until `options.signal` aborts, the SDK signs out or
+     * the session ends, or the consumer stops iterating. Transient stream
+     * failures — network errors, 5xx, and an expired or rotated ticket rejected
+     * by `/hooks/events` (401/403) — are retried internally with backoff and
+     * never reach the iterator.
+     *
+     * The iterator throws when minting the hook ticket is refused. The thrown
+     * plain `ServiceError` carries `meta.status` with the refusing HTTP status,
+     * so `for await` consumers can branch on it. Stream diagnostics contain only
+     * SDK allow-listed identifiers; foreign error messages and causes are not
+     * copied.
+     * `options.onReady` schedules catch-up after each server-confirmed ready
+     * stream, including an unchanged ready stream joined by a late subscriber.
+     * Subscribe/consume before draining stored rows; notifications are not replay.
+     */
+    subscribe(subscriptions: HookSubscription[], options?: SubscribeOptions): AsyncIterable<HookEvent>;
+    register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
+    list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
+    unregister(id: string, options?: HookWebhookUnregisterOptions): Promise<Result<void>>;
+}
+
+export type { HookSubscription as H, IHooksService as I, SubscribeOptions as S, HooksServiceConfig as a, HookEvent as b, HookWebhookRegistration as c, HookWebhookRecord as d, HookWebhookListOptions as e, HookWebhookUnregisterOptions as f, HookServiceName as g, HookStreamEvent as h, HookStreamRetryConfig as i, HookWebhookScope as j };

package/dist/ISQLService-Aly1CBsW.d.ts

@@ -0,0 +1,242 @@
+import { f as Result, c as IService } from './types-CSd0RYir.js';
+
+/**
+ * SQL Service Types
+ *
+ * Type definitions for the SQL service operations.
+ */
+/**
+ * Configuration for SQLService.
+ */
+interface SQLServiceConfig {
+    /**
+     * Default database name.
+     * If not set, operations default to "default".
+     */
+    defaultDatabase?: string;
+    /**
+     * Timeout in milliseconds for each SQL request, including reading the
+     * response body. When it elapses the request is aborted and the operation
+     * returns an `ErrorCodes.TIMEOUT` error. Unset (the default), `0`, or
+     * `Infinity` means no timeout.
+     */
+    timeout?: number;
+    /** Allow additional config properties */
+    [key: string]: unknown;
+}
+/**
+ * Options for SQL query operations.
+ */
+interface QueryOptions {
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+    /** Maximum rows the node may return. Nodes without limit support ignore it. */
+    maxRows?: number;
+    /** Maximum serialized result bytes the node may return. */
+    maxBytes?: number;
+    /** Redact query failure details before return and ordinary service-error events. */
+    redactErrors?: boolean;
+}
+/**
+ * Options for SQL execute operations.
+ */
+interface ExecuteOptions {
+    /**
+     * Schema initialization statements (CREATE TABLE IF NOT EXISTS ...).
+     * Executed before the main statement on first write.
+     */
+    schema?: string[];
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+    /** Redact execute failure details before return and ordinary service-error events. */
+    redactErrors?: boolean;
+}
+/**
+ * Options for SQL batch operations.
+ */
+interface BatchOptions {
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+    /** Redact batch failure details before return and ordinary service-error events. */
+    redactErrors?: boolean;
+}
+/**
+ * A SQL value: null, number, string, or binary data.
+ */
+type SqlValue = null | number | string | Uint8Array;
+/**
+ * A SQL statement with optional parameters.
+ */
+interface SqlStatement {
+    sql: string;
+    params?: SqlValue[];
+}
+/**
+ * Response from SQL query operations.
+ */
+interface QueryResponse<T = Record<string, unknown>> {
+    columns: string[];
+    rows: T[][];
+    rowCount: number;
+}
+/**
+ * Response from SQL execute operations.
+ */
+interface ExecuteResponse {
+    changes: number;
+    lastInsertRowId: number | null;
+}
+/**
+ * Response from SQL batch operations.
+ */
+interface BatchResponse {
+    results: ExecuteResponse[];
+}
+/**
+ * A versioned SQL migration owned by an application or SDK subsystem.
+ */
+interface SqlMigration {
+    /**
+     * Stable migration id within the namespace, e.g. "001_initial".
+     */
+    id: string;
+    /**
+     * SQL statements to apply when this migration has not been recorded.
+     * Statements should be idempotent where SQLite supports it.
+     */
+    sql: Array<string | SqlStatement>;
+}
+/**
+ * Options for applying SQL migrations.
+ */
+interface SqlMigrationApplyOptions {
+    /**
+     * Namespace for this migration set, usually an app id or SDK subsystem.
+     */
+    namespace: string;
+    /**
+     * Ordered migration list.
+     */
+    migrations: SqlMigration[];
+    /**
+     * Custom abort signal for migration operations.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Result from applying SQL migrations.
+ */
+interface SqlMigrationApplyResponse {
+    database: string;
+    namespace: string;
+    status: "already_current" | "applied";
+    applied: string[];
+    skipped: string[];
+}
+/**
+ * SQL service action types.
+ *
+ * URNs derive from the canonical capability registry in `@tinycloud/bootstrap`
+ * (TC-112 single source of truth, vendored from tinycloud-node). `insert`,
+ * `update`, and `delete` were dropped — zero client refs and never accepted
+ * node-side. `select` is a deprecated alias of `read`. `execute`/`export` are
+ * request-kind artifacts, not grantable capabilities: the node routes them by
+ * request-body kind, so they are absent from the registry but kept here as the
+ * invocation ability the client sends today (wire alignment tracked in TC-114).
+ */
+declare const SQLAction: {
+    readonly READ: "tinycloud.sql/read";
+    readonly WRITE: "tinycloud.sql/write";
+    readonly SCHEMA: "tinycloud.sql/schema";
+    readonly ADMIN: "tinycloud.sql/admin";
+    readonly SELECT: "tinycloud.sql/select";
+    readonly EXECUTE: "tinycloud.sql/execute";
+    readonly EXPORT: "tinycloud.sql/export";
+    readonly ALL: "tinycloud.sql/*";
+};
+type SQLActionType = (typeof SQLAction)[keyof typeof SQLAction];
+
+/**
+ * ISQLService - Interface for SQL service.
+ *
+ * Platform-agnostic interface for SQL database operations.
+ */
+
+/**
+ * Migration helper bound to a specific database.
+ */
+interface ISQLMigrations {
+    /**
+     * Apply ordered, app-owned migrations and record completed ids.
+     */
+    apply(options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
+}
+/**
+ * Database handle interface for operations on a specific named database.
+ */
+interface IDatabaseHandle {
+    /** The database name */
+    readonly name: string;
+    /** Versioned schema migration helper. */
+    readonly migrations: ISQLMigrations;
+    /**
+     * Execute a SQL query and return rows.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
+    /**
+     * Execute a SQL statement and return change count.
+     */
+    execute(sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
+    /**
+     * Execute multiple statements in a transaction.
+     */
+    batch(statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
+    /**
+     * Execute a named prepared statement from delegation caveats.
+     */
+    executeStatement(name: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse | ExecuteResponse>>;
+    /**
+     * Export the raw SQLite database file.
+     */
+    export(options?: QueryOptions): Promise<Result<Blob>>;
+}
+/**
+ * SQL service interface.
+ *
+ * Provides SQL database operations with:
+ * - Result type pattern (no throwing)
+ * - Named database handles
+ * - Configurable timeouts
+ * - Abort signal support
+ */
+interface ISQLService extends IService {
+    /**
+     * Get a handle to a named database.
+     * @param name - Database name (defaults to "default")
+     */
+    db(name?: string): IDatabaseHandle;
+    /**
+     * Shortcut: query the default database.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
+    /**
+     * Shortcut: execute on the default database.
+     */
+    execute(sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
+    /**
+     * Shortcut: batch on the default database.
+     */
+    batch(statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
+    /**
+     * Service configuration.
+     */
+    readonly config: SQLServiceConfig;
+}
+
+export { type BatchOptions as B, type ExecuteOptions as E, type IDatabaseHandle as I, type QueryOptions as Q, SQLAction as S, type BatchResponse as a, type ExecuteResponse as b, type ISQLMigrations as c, type ISQLService as d, type QueryResponse as e, type SQLActionType as f, type SQLServiceConfig as g, type SqlMigration as h, type SqlMigrationApplyOptions as i, type SqlMigrationApplyResponse as j, type SqlStatement as k, type SqlValue as l };