@alvera-ai/platform-sdk 0.19.1 → 0.19.2-next.g845dfdf

package/.agent/ai_sandbox.md

@@ -157,7 +157,7 @@ trail this trap leaves.
 
 SQL is the second consumer-author surface: WHERE clauses on
 dataset searches (`api.datasets.createUserSearch.search_query`,
-see `data_activation_clients.md` §6.5). Liquid renders some of
+see `data_activation_clients.md` §6.6). Liquid renders some of
 these from templates; others arrive directly as raw SQL
 fragments. Either path lands at the same boundary.
 
@@ -165,7 +165,7 @@ fragments. Either path lands at the same boundary.
 
 - SELECT against the tables exposed by the dataset search aliases
   (`le` for legal entities, `m` for messages, `al` for action logs
-  — see `data_activation_clients.md` §6.5 SQL aliases).
+  — see `data_activation_clients.md` §6.6 SQL aliases).
 - Filter results into the platform's `search_results`
   accumulator scoped to the materialised search id. This is the
   one write the query path performs, and the platform builds it
@@ -305,5 +305,5 @@ guarantees it captures back-stop Layer 1.
 - `account_management.md` §3 — session role vocabularies (Layer 1)
 - `interoperability_contracts.md` §2 — template_config body shape (Layer 2)
 - `workflows.md` gotcha 9 — the `| to_json` vs `| json` trap (Layer 2)
-- `data_activation_clients.md` §6.5 — dataset search SQL aliases (Layer 3)
+- `data_activation_clients.md` §6.6 — dataset search SQL aliases (Layer 3)
 - `mdm.md` — verification surface that composes with Layer 1

package/.agent/data_activation_clients.md

@@ -377,7 +377,7 @@ Three run shapes exist, selected by the bound tool's
 All three produce **log rows** observable through
 `api.dataActivationClients.logs.*` (§6.4), and the canonical way
 to **verify** that ingestion worked is the two-step
-dataset-search pattern in §6.5.
+dataset-search pattern in §6.6.
 
 ### 6.1 Inline JSON ingestion — `.ingest`
 
@@ -397,7 +397,7 @@ const { data } = await api.dataActivationClients.ingest(
 The response returns **immediately after enqueueing**, not
 after ingestion completes. To know when the row has actually
 been written, poll the logs (§6.4) or use the verification
-pattern (§6.5).
+pattern (§6.6).
 
 The `batch_id` is the most important field on the response —
 every downstream log row and dataset row carries the same
@@ -534,7 +534,110 @@ merge step has committed the ndjson archive. Use
 `output_files.length > 0` as the "this batch's rows are fully
 durable" signal — not just the presence of the log row.
 
-### 6.5 Verifying ingestion: the two-step dataset search
+### 6.5 Runs subresource — `.batches.list` / `.batches.get`
+
+A **run** is one record; the log rows of §6.4 are one record per
+dataset table that run wrote into. Read the run to answer *"is this
+over, and how did it end"*; read the logs for the per-table detail,
+filtered on the same `batch_id`.
+
+Before this record existed, the only way to ask whether a run had
+finished was to count log rows and guess — which cannot tell a run
+still going from one that produced nothing and never will. A run
+that was skipped or that died looked exactly like a slow one until
+the caller's timeout expired.
+
+```
+batch_id     UUID — the run identifier, the same one `.ingest`,
+                    `.ingestFile` and `.runManually` hand back, and the
+                    one stamped on every per-table log row of this run
+client_id    UUID — the owning activation client
+closed_at    ISO timestamp | null — when the run was attempted and
+                    exhausted. Null while it is still going. It does NOT
+                    mean rows landed and it does NOT mean the archive was
+                    merged — read `status` for the outcome, and only once
+                    this is set.
+status       'processing' | 'succeeded' | 'partial' | 'skipped' | 'failed'
+rows_total   number — source rows enqueued for this run. The run's own
+                    count; each per-table log keeps its own.
+inserted_at  ISO timestamp — when the run started
+```
+
+**`status` means nothing until `closed_at` is set.** A run in flight
+always reads `processing`. Once it is closed:
+
+| status | what happened |
+|---|---|
+| `succeeded` | it ran and nothing was refused |
+| `partial` | it ran and at least one row was refused on the way in; the rows that landed are still there |
+| `skipped` | it ran and there was nothing to do — empty file, every row filtered out, or the client has no contracts |
+| `failed` | it died before writing anything |
+
+```typescript
+// Paginated list of runs for an activation client. Takes the full Flop
+// query (page / page_size / order_by / order_directions / filters —
+// type_naming.md); without it, page 1 only.
+const { data } = await api.dataActivationClients.batches.list(
+  tenantSlug, datalakeSlug, activationClientSlug,
+  { page: 1, page_size: 50, order_by: ['inserted_at'], order_directions: ['desc'] },
+)
+// data.data — array of run records; data.meta — pagination
+
+// Fetch one run by its batch_id.
+const { data: run } = await api.dataActivationClients.batches.get(
+  tenantSlug, datalakeSlug, activationClientSlug, batchId,
+)
+```
+
+> **The fourth argument is the `batch_id`, not the record's `id`.**
+> A run record carries both, and both are UUIDs. The route looks the
+> run up by its `batch_id` — the identifier the ingest handed you — so
+> passing the record's own `id` is a **404**, not a type error.
+
+#### Waiting on a run
+
+This is what the run record is for. Poll until `closed_at` is set,
+then branch on `status` — never poll `status` alone, because a run
+in flight reads `processing` forever and tells you nothing:
+
+```typescript
+const { data: ingest } = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, activationClientSlug, { data: row },
+)
+
+const deadline = Date.now() + 120_000
+let run
+for (;;) {
+  const { data } = await api.dataActivationClients.batches.get(
+    tenantSlug, datalakeSlug, activationClientSlug, ingest.batch_id,
+  )
+  if (data.closed_at != null) { run = data; break }
+  if (Date.now() > deadline) throw new Error(`run ${ingest.batch_id} never closed`)
+  await new Promise((r) => setTimeout(r, 1_000))
+}
+
+if (run.status === 'failed') {
+  throw new Error(`run ${ingest.batch_id} failed before writing anything`)
+}
+if (run.status === 'skipped') {
+  throw new Error(`run ${ingest.batch_id} had nothing to do — check the row filter and the client's contracts`)
+}
+// 'succeeded' or 'partial' — the run is over and rows were written.
+// For a partial, read the log rows (§6.4) for which table refused what.
+```
+
+A run that failed or was skipped **ends the wait immediately, carrying
+why**. That is the whole difference from counting rows: a blind poll
+spends its full timeout and then reports nothing about the cause.
+
+> **`closed_at` is not the same as "my row is queryable".** It says the
+> run is over. It does not say the archive was merged (that is
+> `output_files` on the log rows, §6.4), and for one specific row it
+> does not replace the landing check in §6.6 — it makes that check a
+> single read after the run is known finished, instead of a guess
+> against a deadline.
+
+### 6.6 Verifying ingestion: the two-step dataset search
 
 > **Simplest landing check — `executeSql`.** Ingestion is async (the row
 > commits a moment after the `202`). When you just need to know a row
@@ -701,7 +804,7 @@ screen. Pick the mode by which of those two readers you are serving.
    response carries `batch_id` + `jobs_count`, signalling that
    downstream jobs have been enqueued — not that they've
    completed. Poll logs (or use the search verification
-   pattern in §6.5) before treating the row as ingested.
+   pattern in §6.6) before treating the row as ingested.
 
 7. **`dataset_updated > 0` is the load-bearing freshness
    gate.** `rows_ingested` flips as soon as the per-row job

package/.agent/datalakes.md

@@ -110,7 +110,7 @@ The platform does NOT expose a query API over the archive itself —
 cold reads happen externally so the platform's processes aren't
 responsible for analytical workloads. Live data lives in the
 datalake's Postgres halves (queryable via the dataset search
-two-step pattern in `data_activation_clients.md` §6.5); historical
+two-step pattern in `data_activation_clients.md` §6.6); historical
 data lives in the cloud-storage buckets configured here.
 
 ### Canonical create body

package/.agent/interoperability_contracts.md

@@ -299,7 +299,7 @@ in the datalake and there is nothing to search afterwards. The
 contract's `resource_type` destination) runs only when the DAC
 worker ingests a row — i.e. on `dataActivationClients.ingest`, not
 on `.run`. To prove a row *landed*, ingest and then query by
-`batch_id` (see `data_activation_clients.md` §6.5).
+`batch_id` (see `data_activation_clients.md` §6.6).
 
 ```typescript
 const { data: result } = await api.interoperabilityContracts.run(

package/.agent/mdm.md

@@ -339,7 +339,7 @@ SDK surface:
 
 Today there is no `.list`, `.get`, or `.metadata` on the MDM
 namespace — subjects themselves are queried through the dataset
-search surface (see `data_activation_clients.md` §6.5), not
+search surface (see `data_activation_clients.md` §6.6), not
 through `api.mdm`.
 
 ## 6. Gotchas

package/.agent/mock-services.md

@@ -95,21 +95,21 @@ flowchart TD
     end
 ```
 
-**It lives in this repo**, at `cloudflare-workers/mock/`. Deploy from a normal checkout:
+**It lives in this repo**, at `cloudflare/workers/mock/`. Deploy from a normal checkout:
 
 ```bash
-cd cloudflare-workers/mock && wrangler deploy
+cd cloudflare/workers/mock && wrangler deploy
 ```
 
 The single line that makes this work without a vendored copy of the corpus:
 
 ```jsonc
-"image_build_context": ".."
+"image_build_context": "../../.."
 ```
 
 That sets the Docker build context to the repo root, so the Dockerfile copies
 `wm_mappings/` and `wm_response_files/` from where they already live. Without it
-the context is `cloudflare-workers/mock/` and the corpus would have to be duplicated there —
+the context is `cloudflare/workers/mock/` and the corpus would have to be duplicated there —
 two directories that look identical until they quietly aren't.
 
 ### There is no authentication

package/.agent/workflows.md

@@ -714,7 +714,7 @@ an error to retry.
 tables. For a **platform dataset** the server assigns the alias
 (`le` legal entities, `m` messages, `al` action logs, `d` documents,
 `bo` beneficial owners — same scheme as `data_activation_clients.md`
-§6.5), and `id` is ambiguous across the base query's joins, so always
+§6.6), and `id` is ambiguous across the base query's joins, so always
 prefix it: `le.id`.
 
 For a **generic-table** workflow there is no alias — the run selects

package/dist/index.d.mts

@@ -567,9 +567,9 @@ type DataActivationClientLogResponse = {
    */
   rows_ingested?: number;
   /**
-   * `failed` when the batch died before enqueueing any row — the fetch itself errored, and `rows_ingested` and `input_files` are 0/[] on such a row. `partial` when the batch ran and at least one row was refused on the way in; the rows that landed are still there. Read `error` for the reason in both cases.
+   * `processing` from the moment the slice is enqueued until the batch finishes — the column has no default, so this is written, not assumed. `succeeded` is written once by the batch callback, and only over `processing`. `failed` when the batch died before enqueueing any row — the fetch or the enqueue itself errored, and `rows_ingested` and `input_files` are 0/[] on such a row. `partial` when the batch ran and at least one row was refused on the way in; the rows that landed are still there. Read `error` for the reason in the last two.
    */
-  status?: 'succeeded' | 'partial' | 'failed';
+  status?: 'processing' | 'succeeded' | 'partial' | 'failed';
   readonly updated_at?: string;
 };
 /**
@@ -2150,6 +2150,42 @@ type AiAgentInvokeRequest = {
     [key: string]: unknown;
   };
 };
+/**
+ * DataActivationClientBatchResponse
+ *
+ * One record per run. A run fans out into one `DataActivationClientLog` per dataset table it writes into; this is the run itself. To wait on a run, read `closed_at` here rather than reconstructing it from those logs — it is set exactly once, however the run ended.
+ */
+type DataActivationClientBatchResponse = {
+  /**
+   * Run identifier, stamped on every Oban job and every per-table log row of this run
+   */
+  batch_id: string;
+  /**
+   * Owning Data Activation Client ID
+   */
+  readonly client_id: string;
+  /**
+   * When the run was attempted and exhausted. Null while it is still going. It does not mean rows landed and it does not mean the archive was merged — read `status` for the outcome, and only once this is set.
+   */
+  readonly closed_at?: string | null;
+  /**
+   * Run record ID
+   */
+  readonly id?: string;
+  /**
+   * When the run started
+   */
+  readonly inserted_at?: string;
+  /**
+   * Source rows enqueued for this run. The run's own count; each per-table log keeps its own.
+   */
+  rows_total?: number;
+  /**
+   * How the run ended. **It means nothing until `closed_at` is set** — a run still in flight always reads `processing`. `failed` when the run died before writing anything; `partial` when it ran and at least one row was refused on the way in; `skipped` when it ran and there was nothing to do, because the file was empty, every row was filtered out, or the client has no contracts.
+   */
+  status?: 'processing' | 'succeeded' | 'partial' | 'skipped' | 'failed';
+  readonly updated_at?: string;
+};
 /**
  * AdvancedMigrationResponse
  *
@@ -3445,6 +3481,18 @@ type SqsResponse = {
    */
   region: string;
 };
+/**
+ * DataActivationClientBatchListResponse
+ *
+ * Paginated list of data activation client runs
+ */
+type DataActivationClientBatchListResponse = {
+  /**
+   * List of data activation client runs
+   */
+  data: Array<DataActivationClientBatchResponse>;
+  meta: PaginationMeta;
+};
 /**
  * PaginationMeta
  *
@@ -6593,6 +6641,59 @@ type PlatformApiAdvancedMigrationControllerIndexData = {
   };
   url: '/api/v1/tenants/{tenant_slug}/datalakes/{datalake_slug}/advanced-migrations';
 };
+type PlatformApiDataActivationClientControllerBatchesIndexData = {
+  body?: never;
+  path: {
+    /**
+     * Tenant slug
+     */
+    tenant_slug: string;
+    /**
+     * Datalake slug
+     */
+    datalake_slug: string;
+    /**
+     * Data Activation Client slug
+     */
+    slug: string;
+  };
+  query?: {
+    /**
+     * Items per page (1-100). Defaults to the resource's Flop default when omitted.
+     */
+    page_size?: number;
+    /**
+     * Page number (1-indexed). Defaults to 1 when omitted.
+     */
+    page?: number;
+    /**
+     * Fields to sort by, in order of precedence. Must appear in the resource schema's Flop `sortable:` list — unknown fields return 422.
+     */
+    order_by?: Array<string>;
+    /**
+     * Sort direction(s), pair-wise with `order_by`. `asc` or `desc`. Defaults to `asc` per unpaired `order_by` entry.
+     */
+    order_directions?: Array<'asc' | 'desc'>;
+    /**
+     * Flop-native filter array. URL shape: `?filters[][field]=status&filters[][op]=%3D%3D&filters[][value]=pending` (empty brackets — consecutive `[]` entries group into one filter object per element; indexed brackets parse as a map and fail the array cast with 422). `op` is the symbol, percent-encoded — `%3D%3D` for `==`, `%3E%3D` for `>=` — not a word like `equal`; anything outside the enum above is a 422 before the request reaches Flop. Omit `op` entirely for equality. Unknown fields return 422 via Flop validation at the context layer.
+     */
+    filters?: Array<{
+      /**
+       * Filterable field name (must be in the resource's `filterable:`)
+       */
+      field: string;
+      /**
+       * Comparison operator. Defaults to `==` when omitted.
+       */
+      op?: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'empty' | 'not_empty' | 'like' | 'ilike' | 'like_and' | 'like_or' | 'ilike_and' | 'ilike_or' | 'in' | 'not_in' | 'contains' | 'not_contains';
+      /**
+       * Filter value — shape depends on `field` and `op`.
+       */
+      value: unknown;
+    }>;
+  };
+  url: '/api/v1/tenants/{tenant_slug}/datalakes/{datalake_slug}/data-activation-clients/{slug}/batches';
+};
 type PlatformApiAiAgentControllerIndexData = {
   body?: never;
   path: {
@@ -8353,6 +8454,18 @@ declare function _buildApi(myClient: Client): {
         response: Response;
       }>;
     };
+    batches: {
+      list: (tenantSlug: string, datalakeSlug: string, slug: string, query?: PlatformApiDataActivationClientControllerBatchesIndexData["query"]) => Promise<{
+        data: DataActivationClientBatchListResponse;
+        request: Request;
+        response: Response;
+      }>;
+      get: (tenantSlug: string, datalakeSlug: string, slug: string, batchId: string) => Promise<{
+        data: DataActivationClientBatchResponse;
+        request: Request;
+        response: Response;
+      }>;
+    };
   };
   interoperabilityContracts: {
     list: (tenantSlug: string, datalakeSlug: string, query?: PlatformApiInteroperabilityContractControllerIndexData["query"]) => Promise<{
@@ -8535,5 +8648,5 @@ declare function _buildApi(myClient: Client): {
 //#region src/index.d.ts
 declare function isEnvironmentName(name: string): name is EnvironmentName;
 //#endregion
-export { type ActionStatusUpdaterCloudWatchQueryRequest, type ActionStatusUpdaterRequestWritable, type ActionStatusUpdaterResponse, type ActionStatusUpdaterRestCallRequest, ActionType, type AdvancedMigrationListResponse, type AdvancedMigrationRequest, type AdvancedMigrationResponse, type AgenticWorkflowListResponse, type AgenticWorkflowRequestWritable, type AgenticWorkflowResponse, type AiAgentRequestWritable, type AiAgentResponse, type AlveraApiError, type AlveraClient, type ApiConfig, type ApiDebugConfig, type BatchLogListResponse, type BatchLogResponse, type ConnectedAppListResponse, type ConnectedAppRequestWritable, type ConnectedAppResponse, type CreateActionStatusUpdaterRequest, type CreateAiAgentRequest, type CreateGenericTableRequest, type CreateSessionParams, DEFAULT_ENVIRONMENT, type DataActivationClientListResponse, type DataActivationClientLogListResponse, type DataActivationClientLogResponse, type DataActivationClientRequestWritable, type DataActivationClientResponse, type DataSourceRequest, type DataSourceRequestWritable, type DataSourceResponse, type DatalakeRequestWritable, type DatalakeResponse, type DatasetMetadataOptions, type DatasetSearchOptions, type DatasetSearchResponse, type DerivedLakeTablesResponse, type DownloadUrlResponse, ENVIRONMENTS, type EnvironmentName, type ErrorResponse, type ExecuteActionRequest, type ExecuteActionResponse, type ExecuteSqlMeta, type ExecuteSqlRequest, type ExecuteSqlResponse, type GenericTableColumnRequest, type GenericTableColumnResponse, type GenericTableResponse, type IngestFileRequest, type IngestRequest, type InteroperabilityContractAiAgentRequestWritable, type InteroperabilityContractListResponse, type InteroperabilityContractRequestWritable, type InteroperabilityContractResponse, type InteroperabilityRunRequest, type InteroperabilityRunResponse, type MdmVerifyRequest, type MdmVerifyResponse, type PaginationMeta, type PlatformApi, type ResolvePageRequest, type ResyncTableRequest, type ResyncTableResponse, type RunManuallyRequestWritable, type RunManuallyResponse, type RunWorkflowRequest, type RunWorkflowResponse, type SessionResponse, type SessionResult, type SyncRoutesResponse, type TemplateConfig, type TenantListResponse, type TenantResponse, type TextToSqlRequest, type TextToSqlResponse, ToolIntent, type ToolListResponse, type ToolRequest, type ToolRequestWritable, type ToolResponse, type ToolTwilioRequest, type ToolTwilioRequestWritable, type ToolTwilioResponse, type TwilioRequest, type TwilioRequestWritable, type TwilioResponse, type UpdatePageRequest, type UploadLinkRequest, type UploadLinkResponse, type WorkflowAiAgentRequestWritable, type WorkflowLogListResponse, type WorkflowLogResponse, type WorkflowRunListResponse, type WorkflowRunResponse, createBootstrapSession, createIsolatedPlatformApi, createPlatformApi, createSession, isEnvironmentName, revokeSession };
+export { type ActionStatusUpdaterCloudWatchQueryRequest, type ActionStatusUpdaterRequestWritable, type ActionStatusUpdaterResponse, type ActionStatusUpdaterRestCallRequest, ActionType, type AdvancedMigrationListResponse, type AdvancedMigrationRequest, type AdvancedMigrationResponse, type AgenticWorkflowListResponse, type AgenticWorkflowRequestWritable, type AgenticWorkflowResponse, type AiAgentRequestWritable, type AiAgentResponse, type AlveraApiError, type AlveraClient, type ApiConfig, type ApiDebugConfig, type BatchLogListResponse, type BatchLogResponse, type ConnectedAppListResponse, type ConnectedAppRequestWritable, type ConnectedAppResponse, type CreateActionStatusUpdaterRequest, type CreateAiAgentRequest, type CreateGenericTableRequest, type CreateSessionParams, DEFAULT_ENVIRONMENT, type DataActivationClientBatchListResponse, type DataActivationClientBatchResponse, type DataActivationClientListResponse, type DataActivationClientLogListResponse, type DataActivationClientLogResponse, type DataActivationClientRequestWritable, type DataActivationClientResponse, type DataSourceRequest, type DataSourceRequestWritable, type DataSourceResponse, type DatalakeRequestWritable, type DatalakeResponse, type DatasetMetadataOptions, type DatasetSearchOptions, type DatasetSearchResponse, type DerivedLakeTablesResponse, type DownloadUrlResponse, ENVIRONMENTS, type EnvironmentName, type ErrorResponse, type ExecuteActionRequest, type ExecuteActionResponse, type ExecuteSqlMeta, type ExecuteSqlRequest, type ExecuteSqlResponse, type GenericTableColumnRequest, type GenericTableColumnResponse, type GenericTableResponse, type IngestFileRequest, type IngestRequest, type InteroperabilityContractAiAgentRequestWritable, type InteroperabilityContractListResponse, type InteroperabilityContractRequestWritable, type InteroperabilityContractResponse, type InteroperabilityRunRequest, type InteroperabilityRunResponse, type MdmVerifyRequest, type MdmVerifyResponse, type PaginationMeta, type PlatformApi, type ResolvePageRequest, type ResyncTableRequest, type ResyncTableResponse, type RunManuallyRequestWritable, type RunManuallyResponse, type RunWorkflowRequest, type RunWorkflowResponse, type SessionResponse, type SessionResult, type SyncRoutesResponse, type TemplateConfig, type TenantListResponse, type TenantResponse, type TextToSqlRequest, type TextToSqlResponse, ToolIntent, type ToolListResponse, type ToolRequest, type ToolRequestWritable, type ToolResponse, type ToolTwilioRequest, type ToolTwilioRequestWritable, type ToolTwilioResponse, type TwilioRequest, type TwilioRequestWritable, type TwilioResponse, type UpdatePageRequest, type UploadLinkRequest, type UploadLinkResponse, type WorkflowAiAgentRequestWritable, type WorkflowLogListResponse, type WorkflowLogResponse, type WorkflowRunListResponse, type WorkflowRunResponse, createBootstrapSession, createIsolatedPlatformApi, createPlatformApi, createSession, isEnvironmentName, revokeSession };
 //# sourceMappingURL=index.d.mts.map