@stackbone/sdk 0.1.0-alpha.0 → 0.1.0-alpha.2

package/index.d.cts

@@ -19,10 +19,9 @@ interface ClientConfig {
     agentId?: string;
     /**
      * Postgres connection string consumed by `client.rag` and the platform
-     * observability exporter. Falls back to `DATABASE_URL`. Note: `client.database`
-     * uses `STACKBONE_POSTGRES_URL` instead — the two env vars are intentionally
-     * different so that the SDK's own DB pool stays decoupled from the legacy
-     * `DATABASE_URL` consumers until `feature 30` consolidates them.
+     * observability exporter. Falls back to `STACKBONE_POSTGRES_URL` — the same
+     * env var `client.database` reads, so a single connection string covers
+     * every SDK consumer that talks to the agent's Postgres.
      */
     databaseUrl?: string;
     openrouterKey?: string;
@@ -46,14 +45,16 @@ interface ClientConfig {
      */
     installationId?: string;
     s3?: {
-        /** Falls back to `AWS_ACCESS_KEY_ID`. */
+        /** Falls back to `STACKBONE_S3_ACCESS_KEY`. */
         accessKeyId?: string;
-        /** Falls back to `AWS_SECRET_ACCESS_KEY`. */
+        /** Falls back to `STACKBONE_S3_SECRET_KEY`. */
         secretAccessKey?: string;
-        /** Falls back to `S3_ENDPOINT`. */
+        /** Falls back to `STACKBONE_S3_ENDPOINT`. */
         endpoint?: string;
-        /** Physical R2/S3 bucket scoped to the agent. Falls back to `S3_BUCKET`. */
+        /** Physical R2/S3 bucket scoped to the agent. Falls back to `STACKBONE_S3_BUCKET`. */
         bucket?: string;
+        /** AWS region. Falls back to `STACKBONE_S3_REGION`, defaults to `'auto'` (R2/MinIO). */
+        region?: string;
     };
     otel?: {
         exporterOtlpEndpoint?: string;
@@ -337,7 +338,7 @@ declare class ConnectionsFacade {
     list(): Promise<Result<readonly never[]>>;
 }
 
-/** Emit events to the workspace event bus. */
+/** Emit events to the organization event bus. */
 declare class EventsFacade {
     private readonly _http;
     private readonly _gate;
@@ -424,7 +425,7 @@ declare class SecretsFacade {
     gate?: ModuleGate);
     get(name: string): Promise<Result<string>>;
     /**
-     * Names absent from the workspace come back as omissions in the response —
+     * Names absent from the organization come back as omissions in the response —
      * the returned map only contains entries the control plane actually has.
      * Callers that need "all-or-nothing" semantics should diff the keys.
      */
@@ -1007,6 +1008,53 @@ type RagIngestProgress = {
     jobId: string;
     error: string;
 };
+interface IngestJobStartArgs {
+    collection: string;
+    source: string;
+    totalChunks: number;
+}
+interface IngestJobProgressArgs {
+    jobId: string;
+    processedChunks: number;
+    totalChunks: number;
+    currentDocument?: {
+        source: string;
+        ordinal: number;
+    };
+}
+interface IngestJobCompleteArgs {
+    jobId: string;
+    totalChunks: number;
+}
+interface IngestJobFailArgs {
+    jobId: string;
+    error: string;
+}
+interface IngestJobWriter {
+    /**
+     * Allocates a `stackbone_rag_jobs` row in `running` state and returns its
+     * id. Caller is expected to surface this id to the user before any
+     * progress event fires so a `client.rag.ingestAsync` consumer can
+     * immediately address the job (e.g. `POST /api/rag/jobs/:jobId/cancel`).
+     */
+    start(args: IngestJobStartArgs): Promise<Result<{
+        jobId: string;
+    }>>;
+    /** Idempotent — last write wins on `progress` jsonb. */
+    progress(args: IngestJobProgressArgs): Promise<void>;
+    /** Marks the row terminal (status='succeeded'). */
+    complete(args: IngestJobCompleteArgs): Promise<void>;
+    /** Marks the row terminal (status='failed') and stores the error message. */
+    fail(args: IngestJobFailArgs): Promise<void>;
+    /**
+     * Polled between chunk batches. Returning `true` makes the pipeline abort
+     * with `rag_ingest_cancelled`, leaving the row in whatever terminal state
+     * the writer transitions it to next (typically `cancelled`).
+     */
+    isCancelled(args: {
+        jobId: string;
+    }): Promise<boolean>;
+}
 
 interface ParseOptions {
     /** MIME type override. If omitted, the parser sniffs the input (Blob.type or PDF magic bytes). */
@@ -1120,13 +1168,26 @@ interface IngestAsyncHandle {
  * an operation hits `42P01 relation does not exist`, the pipeline returns
  * `SdkError('rag_schema_missing')` with an actionable hint.
  */
+/**
+ * Test-only seams accepted by `RagModule`. Production callers leave these
+ * unset — they are injected by `ingest-async.spec.ts` to substitute the
+ * shared-pool lookup and the SQL-backed job writer.
+ */
+interface RagModuleTestDeps {
+    /** Replaces the lazy `getDatabaseHandle()` lookup used by `ingestAsync`. */
+    sqlProvider?: () => Result<Sql>;
+    /** Builds an `IngestJobWriter` from the resolved SQL. Defaults to `createSqlJobWriter`. */
+    jobWriterFactory?: (sql: Sql) => IngestJobWriter;
+}
 declare class RagModule {
     private readonly _resolved;
     private readonly _getAi;
     private readonly _gate;
+    private readonly _testSqlOverride?;
+    private readonly _testJobWriterFactory?;
     constructor(_resolved: ResolvedConfig, _getAi: () => AiModule, 
     /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
+    gate?: ModuleGate, testDeps?: RagModuleTestDeps);
     ingest(request: IngestRequest): Promise<Result<IngestResponse>>;
     /**
      * Asynchronous ingest. Allocates a `stackbone_rag_jobs` row, returns the
@@ -1143,10 +1204,6 @@ declare class RagModule {
      * exactly one pool against `STACKBONE_POSTGRES_URL`.
      */
     ingestAsync(request: IngestRequest): Promise<Result<IngestAsyncHandle>>;
-    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-    private _testJobWriter?;
-    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-    private _testSqlOverride?;
     delete(ids: string | string[], options?: DeleteOptions): Promise<Result<DeleteResponse>>;
     deleteWhere(filter: Record<string, unknown>, options?: DeleteOptions): Promise<Result<DeleteResponse>>;
     retrieve(request: RetrieveRequest): Promise<Result<RetrieveHit[]>>;
@@ -1267,6 +1324,7 @@ declare class StorageBucket {
     getPublicUrl(key: string): Result<string>;
     getSignedUploadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
     getSignedDownloadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
+    private signUrl;
     /**
      * Resolves S3 settings, validates the user key, and prefixes it with
      * `${agentId}/${bucketName}/`. Rejects path-traversal segments (`..`) so a

package/index.d.ts

@@ -19,10 +19,9 @@ interface ClientConfig {
     agentId?: string;
     /**
      * Postgres connection string consumed by `client.rag` and the platform
-     * observability exporter. Falls back to `DATABASE_URL`. Note: `client.database`
-     * uses `STACKBONE_POSTGRES_URL` instead — the two env vars are intentionally
-     * different so that the SDK's own DB pool stays decoupled from the legacy
-     * `DATABASE_URL` consumers until `feature 30` consolidates them.
+     * observability exporter. Falls back to `STACKBONE_POSTGRES_URL` — the same
+     * env var `client.database` reads, so a single connection string covers
+     * every SDK consumer that talks to the agent's Postgres.
      */
     databaseUrl?: string;
     openrouterKey?: string;
@@ -46,14 +45,16 @@ interface ClientConfig {
      */
     installationId?: string;
     s3?: {
-        /** Falls back to `AWS_ACCESS_KEY_ID`. */
+        /** Falls back to `STACKBONE_S3_ACCESS_KEY`. */
         accessKeyId?: string;
-        /** Falls back to `AWS_SECRET_ACCESS_KEY`. */
+        /** Falls back to `STACKBONE_S3_SECRET_KEY`. */
         secretAccessKey?: string;
-        /** Falls back to `S3_ENDPOINT`. */
+        /** Falls back to `STACKBONE_S3_ENDPOINT`. */
         endpoint?: string;
-        /** Physical R2/S3 bucket scoped to the agent. Falls back to `S3_BUCKET`. */
+        /** Physical R2/S3 bucket scoped to the agent. Falls back to `STACKBONE_S3_BUCKET`. */
         bucket?: string;
+        /** AWS region. Falls back to `STACKBONE_S3_REGION`, defaults to `'auto'` (R2/MinIO). */
+        region?: string;
     };
     otel?: {
         exporterOtlpEndpoint?: string;
@@ -337,7 +338,7 @@ declare class ConnectionsFacade {
     list(): Promise<Result<readonly never[]>>;
 }
 
-/** Emit events to the workspace event bus. */
+/** Emit events to the organization event bus. */
 declare class EventsFacade {
     private readonly _http;
     private readonly _gate;
@@ -424,7 +425,7 @@ declare class SecretsFacade {
     gate?: ModuleGate);
     get(name: string): Promise<Result<string>>;
     /**
-     * Names absent from the workspace come back as omissions in the response —
+     * Names absent from the organization come back as omissions in the response —
      * the returned map only contains entries the control plane actually has.
      * Callers that need "all-or-nothing" semantics should diff the keys.
      */
@@ -1007,6 +1008,53 @@ type RagIngestProgress = {
     jobId: string;
     error: string;
 };
+interface IngestJobStartArgs {
+    collection: string;
+    source: string;
+    totalChunks: number;
+}
+interface IngestJobProgressArgs {
+    jobId: string;
+    processedChunks: number;
+    totalChunks: number;
+    currentDocument?: {
+        source: string;
+        ordinal: number;
+    };
+}
+interface IngestJobCompleteArgs {
+    jobId: string;
+    totalChunks: number;
+}
+interface IngestJobFailArgs {
+    jobId: string;
+    error: string;
+}
+interface IngestJobWriter {
+    /**
+     * Allocates a `stackbone_rag_jobs` row in `running` state and returns its
+     * id. Caller is expected to surface this id to the user before any
+     * progress event fires so a `client.rag.ingestAsync` consumer can
+     * immediately address the job (e.g. `POST /api/rag/jobs/:jobId/cancel`).
+     */
+    start(args: IngestJobStartArgs): Promise<Result<{
+        jobId: string;
+    }>>;
+    /** Idempotent — last write wins on `progress` jsonb. */
+    progress(args: IngestJobProgressArgs): Promise<void>;
+    /** Marks the row terminal (status='succeeded'). */
+    complete(args: IngestJobCompleteArgs): Promise<void>;
+    /** Marks the row terminal (status='failed') and stores the error message. */
+    fail(args: IngestJobFailArgs): Promise<void>;
+    /**
+     * Polled between chunk batches. Returning `true` makes the pipeline abort
+     * with `rag_ingest_cancelled`, leaving the row in whatever terminal state
+     * the writer transitions it to next (typically `cancelled`).
+     */
+    isCancelled(args: {
+        jobId: string;
+    }): Promise<boolean>;
+}
 
 interface ParseOptions {
     /** MIME type override. If omitted, the parser sniffs the input (Blob.type or PDF magic bytes). */
@@ -1120,13 +1168,26 @@ interface IngestAsyncHandle {
  * an operation hits `42P01 relation does not exist`, the pipeline returns
  * `SdkError('rag_schema_missing')` with an actionable hint.
  */
+/**
+ * Test-only seams accepted by `RagModule`. Production callers leave these
+ * unset — they are injected by `ingest-async.spec.ts` to substitute the
+ * shared-pool lookup and the SQL-backed job writer.
+ */
+interface RagModuleTestDeps {
+    /** Replaces the lazy `getDatabaseHandle()` lookup used by `ingestAsync`. */
+    sqlProvider?: () => Result<Sql>;
+    /** Builds an `IngestJobWriter` from the resolved SQL. Defaults to `createSqlJobWriter`. */
+    jobWriterFactory?: (sql: Sql) => IngestJobWriter;
+}
 declare class RagModule {
     private readonly _resolved;
     private readonly _getAi;
     private readonly _gate;
+    private readonly _testSqlOverride?;
+    private readonly _testJobWriterFactory?;
     constructor(_resolved: ResolvedConfig, _getAi: () => AiModule, 
     /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
+    gate?: ModuleGate, testDeps?: RagModuleTestDeps);
     ingest(request: IngestRequest): Promise<Result<IngestResponse>>;
     /**
      * Asynchronous ingest. Allocates a `stackbone_rag_jobs` row, returns the
@@ -1143,10 +1204,6 @@ declare class RagModule {
      * exactly one pool against `STACKBONE_POSTGRES_URL`.
      */
     ingestAsync(request: IngestRequest): Promise<Result<IngestAsyncHandle>>;
-    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-    private _testJobWriter?;
-    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-    private _testSqlOverride?;
     delete(ids: string | string[], options?: DeleteOptions): Promise<Result<DeleteResponse>>;
     deleteWhere(filter: Record<string, unknown>, options?: DeleteOptions): Promise<Result<DeleteResponse>>;
     retrieve(request: RetrieveRequest): Promise<Result<RetrieveHit[]>>;
@@ -1267,6 +1324,7 @@ declare class StorageBucket {
     getPublicUrl(key: string): Result<string>;
     getSignedUploadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
     getSignedDownloadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
+    private signUrl;
     /**
      * Resolves S3 settings, validates the user key, and prefixes it with
      * `${agentId}/${bucketName}/`. Rejects path-traversal segments (`..`) so a