@supacloud/js 0.24.1 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -186,6 +186,44 @@ The current package focuses on:
186
186
  - `artifacts.get`
187
187
  - `artifacts.link`
188
188
 
189
+ ### Typed task results
190
+
191
+ Task receipts are transport-safe by default: ordinary task methods return an
192
+ unknown result payload. Use an explicit decoder when the application owns the
193
+ result contract; the decoder is retained by the receipt for `get`, `wait`,
194
+ `cancel`, `retry`, and `subscribe`.
195
+
196
+ ```ts
197
+ type InvoiceResult = { invoiceId: string; accepted: boolean };
198
+
199
+ const decodeInvoiceResult = (value: unknown): InvoiceResult => {
200
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
201
+ throw new Error("Invalid invoice result");
202
+ }
203
+ const result = value as Record<string, unknown>;
204
+ if (typeof result.invoiceId !== "string" || typeof result.accepted !== "boolean") {
205
+ throw new Error("Invalid invoice result");
206
+ }
207
+ return { invoiceId: result.invoiceId, accepted: result.accepted };
208
+ };
209
+
210
+ const receipt = await supacloud.tasks.submitTyped(
211
+ "issue-invoice",
212
+ decodeInvoiceResult,
213
+ { body: { invoiceId: "inv-123" } },
214
+ );
215
+ const result = await receipt.wait();
216
+ console.log(result.result?.invoiceId, result.result?.accepted);
217
+ ```
218
+
219
+ The same decoder-first API is available as `getTyped`, `listTyped`,
220
+ `listDlqTyped`, `waitTyped`, `cancelTyped`, `retryTyped`, and `subscribeTyped`.
221
+ Decoder failures throw the sanitized `SupaCloudTaskDecoderError`; its
222
+ `mutationMayHaveApplied` flag is `true` for `cancelTyped` and `retryTyped`, so a
223
+ caller must reconcile the task state instead of blindly repeating the mutation.
224
+ This is runtime validation supplied by the application, not an unchecked
225
+ generic cast or a second platform task schema.
226
+
189
227
  ## Status Subscription
190
228
 
191
229
  `tasks.subscribe()` uses this strategy:
@@ -292,6 +330,30 @@ Queue settings:
292
330
 
293
331
  Management extension conflicts are surfaced as `SupaCloudApiError` with `status`, `code`, and `responseBody`, so callers do not need to parse raw `fetch` responses.
294
332
 
333
+ ## Command Status
334
+
335
+ `commands.submit` and `commands.get` share a runtime-validated status contract:
336
+ `kind: "submission"` means accepted work, with `execution: null`; `kind: "execution"`
337
+ includes the durable execution receipt. Workflow status remains a separate field.
338
+ A completed workflow by itself never proves that an external business effect
339
+ occurred. Use `workflows.get(commandId)` for the full workflow details.
340
+
341
+ `commands.get(commandId)` also accepts `{ tenantId, actorId, command, operationId }`
342
+ for direct executions. The returned commandId is the global dispatch/workflow ID.
343
+ These RPCs remain service-role-only and are not browser authorization boundaries.
344
+
345
+ For submitted work, supply verified `tenantId` and `actorId` on submission, then
346
+ bind the claimed execute step with `createPostgresCommandStore(database, { submission })`.
347
+ The executor preserves the submitted ID and atomically completes or advances the
348
+ same Workflow; it does not create a second command. See
349
+ [migration and worker wiring](../../docs/command-workflow-convergence.md).
350
+
351
+ This is a breaking SDK return-shape change: old top-level `idempotent`, target and
352
+ full-workflow fields are no longer the public command status contract. Identical
353
+ submission replay still deduplicates in SQL. Legacy low-level SQL snapshot/submit
354
+ functions retain their stored submission data; older records are not reclassified
355
+ as confirmed executions.
356
+
295
357
  ## Durable Workflows
296
358
 
297
359
  `supacloud.workflows` coordinates code-defined, linear steps on the project's PostgreSQL and PGMQ runtime. Every workflow RPC is restricted to `service_role`; create this client only in a trusted worker or server process.
@@ -1,33 +1,34 @@
1
- import type { SupabaseClient } from "@supabase/supabase-js";
2
- import type { SupaCloudWorkflowJson, SupaCloudWorkflowRun } from "./workflows.js";
1
+ import { type CommandLookup, type CommandStatus } from "@supacloud/contracts";
2
+ /** Narrow, validated boundary compatible with the Supabase RPC client. */
3
+ export interface CommandRpcClient {
4
+ rpc(functionName: string, args: {
5
+ request: object;
6
+ }): PromiseLike<{
7
+ data: unknown;
8
+ error: unknown;
9
+ }>;
10
+ }
3
11
  export interface SupaCloudCommandSubmitRequest {
4
12
  commandId: string;
5
13
  commandType: string;
6
14
  targetType: string;
7
15
  targetId: string;
8
16
  actorId?: string;
9
- payload?: SupaCloudWorkflowJson;
17
+ /** Required, together with actorId, when binding a submission to a durable executor. */
18
+ tenantId?: string;
19
+ payload?: Record<string, unknown>;
10
20
  maxAttempts?: number;
11
21
  }
12
- export interface SupaCloudCommandReceipt {
13
- commandId: string;
14
- commandType: string;
15
- targetType: string;
16
- targetId: string;
17
- actorId: string | null;
18
- payloadFingerprint: string;
19
- createdAt: string;
20
- idempotent: boolean;
21
- workflow: SupaCloudWorkflowRun;
22
- }
22
+ export type SupaCloudCommandReceipt = CommandStatus;
23
23
  /**
24
24
  * Service-role-only transactional command receipt client. Application-owned
25
25
  * database RPCs can call `supacloud_commands.submit` directly inside a larger
26
26
  * transaction when the domain write and durable enqueue must commit together.
27
27
  */
28
- export declare class SupaCloudCommandsClient<TClient extends SupabaseClient = SupabaseClient> {
28
+ export declare class SupaCloudCommandsClient<TClient extends CommandRpcClient = CommandRpcClient> {
29
29
  private readonly supabase;
30
30
  constructor(supabase: TClient);
31
31
  submit(request: SupaCloudCommandSubmitRequest): Promise<SupaCloudCommandReceipt>;
32
- get(commandId: string): Promise<SupaCloudCommandReceipt | null>;
32
+ get(lookup: string | CommandLookup): Promise<SupaCloudCommandReceipt | null>;
33
+ private request;
33
34
  }
package/dist/index.d.ts CHANGED
@@ -6,6 +6,52 @@ export { createSupaCloudOAuthFetch, type SupaCloudOAuthFetchOptions, } from "./a
6
6
  export * from "./workflows.js";
7
7
  export * from "./commands.js";
8
8
  export * from "./artifacts.js";
9
+ export declare const SUPACLOUD_JS_VERSION = "0.27.1";
10
+ export type SupaCloudCapability = {
11
+ available: boolean;
12
+ source: string;
13
+ version: string | null;
14
+ reason_code: string | null;
15
+ authority_project_ref?: string;
16
+ managed_by_owner?: boolean;
17
+ [key: string]: unknown;
18
+ };
19
+ export type SupaCloudProjectCapabilities = {
20
+ project_ref: string;
21
+ auth_runtime: string;
22
+ schema_version: number;
23
+ platform_version?: string;
24
+ environment?: string;
25
+ storage_backend?: string;
26
+ capabilities: Record<string, SupaCloudCapability>;
27
+ [key: string]: unknown;
28
+ };
29
+ export type SupaCloudEnvironmentInfo = {
30
+ projectRef: string;
31
+ platformVersion: string;
32
+ environment: string;
33
+ schemaVersion: number;
34
+ authRuntime: string;
35
+ storageBackend?: string;
36
+ capabilities: Record<string, SupaCloudCapability>;
37
+ [key: string]: unknown;
38
+ };
39
+ export type SupaCloudStoragePlatformConstraints = {
40
+ max_upload_size_bytes: number;
41
+ max_upload_size_mb: number;
42
+ tus_max_size_bytes: number;
43
+ tus_chunk_max_size_bytes: number;
44
+ streaming_upload_supported: boolean;
45
+ };
46
+ export type SupaCloudStorageUploadConstraints = {
47
+ bucketId: string;
48
+ fileSizeLimit: number | null;
49
+ allowedMimeTypes: string[] | null;
50
+ };
51
+ export type SupaCloudUploadValidationResult = {
52
+ valid: boolean;
53
+ error?: string;
54
+ };
9
55
  export type SupaCloudTaskStatus = "pending" | "leased" | "running" | "retry_scheduled" | "succeeded" | "failed" | "dead_lettered" | "cancelled" | "queued" | "processing" | "completed";
10
56
  export type SupaCloudTaskLogEntry = {
11
57
  timestamp: string;
@@ -23,7 +69,10 @@ export type SupaCloudTaskAttempt = {
23
69
  error: string | null;
24
70
  logs: SupaCloudTaskLogEntry[];
25
71
  };
26
- export type SupaCloudTaskDetail = {
72
+ export type SupaCloudTaskResultDecoder<TResult> = (value: unknown) => TResult;
73
+ /** Alias kept short for consumers that already use decoder terminology. */
74
+ export type SupaCloudTaskDecoder<TResult> = SupaCloudTaskResultDecoder<TResult>;
75
+ export type SupaCloudTaskDetail<TResult = unknown> = {
27
76
  id: string;
28
77
  status: SupaCloudTaskStatus | string;
29
78
  function_slug?: string | null;
@@ -33,7 +82,7 @@ export type SupaCloudTaskDetail = {
33
82
  progress?: number | null;
34
83
  error?: string | null;
35
84
  error_message?: string | null;
36
- result?: unknown;
85
+ result?: TResult;
37
86
  payload?: Record<string, unknown>;
38
87
  attempts?: SupaCloudTaskAttempt[];
39
88
  latest_logs?: SupaCloudTaskLogEntry[];
@@ -44,13 +93,13 @@ export type SupaCloudTaskDetail = {
44
93
  created_at?: string | null;
45
94
  [key: string]: unknown;
46
95
  };
47
- export type SupaCloudTaskSnapshot = {
96
+ export type SupaCloudTaskSnapshot<TResult = unknown> = {
48
97
  id: string;
49
98
  status: SupaCloudTaskStatus | string;
50
99
  progress?: number | null;
51
100
  error?: string | null;
52
101
  updatedAt?: string | null;
53
- raw: unknown;
102
+ raw: SupaCloudTaskDetail<TResult>;
54
103
  };
55
104
  export type SupaCloudTaskListFilters = {
56
105
  status?: string | string[];
@@ -249,28 +298,29 @@ export type SupaCloudTaskWaitOptions = {
249
298
  signal?: AbortSignal;
250
299
  };
251
300
  export type SupaCloudTaskSubscribeState = "connecting" | "realtime" | "polling" | "closed";
252
- export type SupaCloudTaskSubscribeOptions = {
301
+ export type SupaCloudTaskSubscribeOptions<TResult = unknown> = {
253
302
  pollingIntervalMs?: number;
254
303
  realtimeTimeoutMs?: number;
255
304
  reconcileIntervalMs?: number;
256
- onUpdate: (task: SupaCloudTaskSnapshot) => void;
305
+ onUpdate: (task: SupaCloudTaskSnapshot<TResult>) => void;
257
306
  onStateChange?: (state: SupaCloudTaskSubscribeState, details?: {
258
307
  error?: unknown;
259
308
  }) => void;
260
309
  onError?: (error: unknown) => void;
261
310
  stopOnTerminal?: boolean;
262
311
  };
263
- export type SupaCloudTaskReceipt = {
312
+ export type SupaCloudTaskSubscription = {
313
+ readonly connectionState: SupaCloudTaskSubscribeState;
314
+ unsubscribe: () => void;
315
+ };
316
+ export type SupaCloudTaskReceipt<TResult = unknown> = {
264
317
  taskId: string;
265
318
  status: string;
266
- get: () => Promise<SupaCloudTaskDetail>;
267
- wait: (options?: SupaCloudTaskWaitOptions) => Promise<SupaCloudTaskDetail>;
268
- cancel: () => Promise<SupaCloudTaskDetail>;
269
- retry: () => Promise<SupaCloudTaskDetail>;
270
- subscribe: (options: SupaCloudTaskSubscribeOptions) => {
271
- connectionState: SupaCloudTaskSubscribeState;
272
- unsubscribe: () => void;
273
- };
319
+ get: () => Promise<SupaCloudTaskDetail<TResult>>;
320
+ wait: (options?: SupaCloudTaskWaitOptions) => Promise<SupaCloudTaskDetail<TResult>>;
321
+ cancel: () => Promise<SupaCloudTaskDetail<TResult>>;
322
+ retry: () => Promise<SupaCloudTaskDetail<TResult>>;
323
+ subscribe: (options: SupaCloudTaskSubscribeOptions<TResult>) => SupaCloudTaskSubscription;
274
324
  };
275
325
  export type SupaCloudClientOptions<TClient extends SupabaseClient = SupabaseClient> = {
276
326
  supabase: TClient;
@@ -352,26 +402,51 @@ export declare class SupaCloudApiError extends Error {
352
402
  readonly responseBody: unknown;
353
403
  constructor(message: string, status: number, responseBody: unknown);
354
404
  }
405
+ export type SupaCloudTaskDecodeOperation = "get" | "list" | "wait" | "cancel" | "retry" | "subscribe";
406
+ /**
407
+ * A caller-supplied result decoder failed. Decoder errors are sanitized so
408
+ * application result values and decoder implementation details are not leaked.
409
+ */
410
+ export declare class SupaCloudTaskDecoderError extends SupaCloudApiError {
411
+ readonly operation: SupaCloudTaskDecodeOperation;
412
+ readonly code: "TASK_RESULT_INVALID";
413
+ readonly mutationMayHaveApplied: boolean;
414
+ constructor(operation: SupaCloudTaskDecodeOperation);
415
+ }
416
+ /** Compatibility spelling for callers that use the shorter decode term. */
417
+ export { SupaCloudTaskDecoderError as SupaCloudTaskDecodeError };
355
418
  type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
419
+ type ResponseDecoder<T> = (value: unknown) => T;
356
420
  declare class SupaCloudManagementClient<TClient extends SupabaseClient = SupabaseClient> {
357
421
  protected readonly options: Required<SupaCloudClientOptions<TClient>>;
358
422
  constructor(options: Required<SupaCloudClientOptions<TClient>>);
359
423
  protected resolveAccessToken(): Promise<string>;
360
- protected request<T>(path: string, method: HttpMethod, body?: unknown): Promise<T>;
424
+ protected request<T>(path: string, method: HttpMethod, body: unknown, decode: ResponseDecoder<T>): Promise<T>;
361
425
  }
362
426
  declare class SupaCloudTasksClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
363
427
  private createReceipt;
364
- submit(functionName: string, options?: SupaCloudTaskSubmitOptions): Promise<SupaCloudTaskReceipt>;
428
+ private createTypedReceipt;
429
+ submit(functionName: string, options?: SupaCloudTaskSubmitOptions): Promise<SupaCloudTaskReceipt<unknown>>;
430
+ submitTyped<TResult>(functionName: string, decoder: SupaCloudTaskResultDecoder<TResult>, options?: SupaCloudTaskSubmitOptions): Promise<SupaCloudTaskReceipt<TResult>>;
431
+ submitTyped<TResult>(functionName: string, options: SupaCloudTaskSubmitOptions, decoder: SupaCloudTaskResultDecoder<TResult>): Promise<SupaCloudTaskReceipt<TResult>>;
365
432
  get(taskId: string): Promise<SupaCloudTaskDetail>;
433
+ getTyped<TResult>(taskId: string, decoder: SupaCloudTaskResultDecoder<TResult>): Promise<SupaCloudTaskDetail<TResult>>;
366
434
  list(filters?: SupaCloudTaskListFilters): Promise<SupaCloudTaskDetail[]>;
435
+ listTyped<TResult>(decoder: SupaCloudTaskResultDecoder<TResult>, filters?: SupaCloudTaskListFilters): Promise<SupaCloudTaskDetail<TResult>[]>;
436
+ listTyped<TResult>(filters: SupaCloudTaskListFilters, decoder: SupaCloudTaskResultDecoder<TResult>): Promise<SupaCloudTaskDetail<TResult>[]>;
367
437
  cancel(taskId: string): Promise<SupaCloudTaskDetail>;
438
+ cancelTyped<TResult>(taskId: string, decoder: SupaCloudTaskResultDecoder<TResult>): Promise<SupaCloudTaskDetail<TResult>>;
368
439
  retry(taskId: string): Promise<SupaCloudTaskDetail>;
440
+ retryTyped<TResult>(taskId: string, decoder: SupaCloudTaskResultDecoder<TResult>): Promise<SupaCloudTaskDetail<TResult>>;
369
441
  listDlq(limit?: number): Promise<SupaCloudTaskDetail[]>;
442
+ listDlqTyped<TResult>(decoder: SupaCloudTaskResultDecoder<TResult>, limit?: number): Promise<SupaCloudTaskDetail<TResult>[]>;
370
443
  wait(taskId: string, options?: SupaCloudTaskWaitOptions): Promise<SupaCloudTaskDetail>;
371
- subscribe(taskId: string, options: SupaCloudTaskSubscribeOptions): {
372
- readonly connectionState: SupaCloudTaskSubscribeState;
373
- unsubscribe(): void;
374
- };
444
+ waitTyped<TResult>(taskId: string, decoder: SupaCloudTaskResultDecoder<TResult>, options?: SupaCloudTaskWaitOptions): Promise<SupaCloudTaskDetail<TResult>>;
445
+ waitTyped<TResult>(taskId: string, options: SupaCloudTaskWaitOptions, decoder: SupaCloudTaskResultDecoder<TResult>): Promise<SupaCloudTaskDetail<TResult>>;
446
+ subscribe(taskId: string, options: SupaCloudTaskSubscribeOptions): SupaCloudTaskSubscription;
447
+ subscribeTyped<TResult>(taskId: string, decoder: SupaCloudTaskResultDecoder<TResult>, options: SupaCloudTaskSubscribeOptions<TResult>): SupaCloudTaskSubscription;
448
+ subscribeTyped<TResult>(taskId: string, options: SupaCloudTaskSubscribeOptions<TResult>, decoder: SupaCloudTaskResultDecoder<TResult>): SupaCloudTaskSubscription;
449
+ private subscribeInternal;
375
450
  }
376
451
  declare class SupaCloudQueueClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
377
452
  private readonly name;
@@ -442,6 +517,20 @@ declare class SupaCloudSupAuthClient<TClient extends SupabaseClient = SupabaseCl
442
517
  getClientConfig(): Promise<SupaCloudSupAuthClientConfig>;
443
518
  verify(): Promise<SupaCloudSupAuthVerification>;
444
519
  }
520
+ export declare class SupaCloudCapabilitiesClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
521
+ get(): Promise<SupaCloudProjectCapabilities>;
522
+ isAvailable(capabilityKey: string): Promise<boolean>;
523
+ getVersion(): Promise<string>;
524
+ getEnvironment(): Promise<SupaCloudEnvironmentInfo>;
525
+ }
526
+ export declare class SupaCloudStorageClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
527
+ getPlatformConstraints(): Promise<SupaCloudStoragePlatformConstraints>;
528
+ getUploadConstraints(bucketId: string): Promise<SupaCloudStorageUploadConstraints>;
529
+ validateUpload(bucketId: string, file: {
530
+ size: number;
531
+ type?: string;
532
+ }): Promise<SupaCloudUploadValidationResult>;
533
+ }
445
534
  export declare function createSupaCloudClient<TClient extends SupabaseClient = SupabaseClient>(options: SupaCloudClientOptions<TClient>): {
446
535
  supabase: TClient;
447
536
  projectRef: string;
@@ -456,8 +545,12 @@ export declare function createSupaCloudClient<TClient extends SupabaseClient = S
456
545
  artifacts: SupaCloudArtifactsClient<TClient>;
457
546
  supauth: SupaCloudSupAuthClient<TClient>;
458
547
  queues: SupaCloudQueuesClient<TClient>;
548
+ capabilities: SupaCloudCapabilitiesClient<TClient>;
549
+ storage: SupaCloudStorageClient<TClient>;
550
+ getEnvironment: () => Promise<SupaCloudEnvironmentInfo>;
551
+ getVersion: () => Promise<string>;
459
552
  queue: (name: string) => SupaCloudQueueClient<TClient>;
460
553
  functions: {
461
- invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt>;
554
+ invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt<unknown>>;
462
555
  };
463
556
  };