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

package/index.d.cts

@@ -338,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;
@@ -425,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.
      */
@@ -1008,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). */
@@ -1121,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
@@ -1144,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[]>>;
@@ -1268,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

@@ -338,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;
@@ -425,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.
      */
@@ -1008,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). */
@@ -1121,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
@@ -1144,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[]>>;
@@ -1268,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