@supacloud/js 0.15.0 → 0.16.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
@@ -8,6 +8,7 @@ It does **not** replace [`@supabase/supabase-js`](https://www.npmjs.com/package/
8
8
  - task detail and list APIs
9
9
  - cancel / retry helpers
10
10
  - Realtime subscription with polling fallback
11
+ - queue send / receive / ack / release / fail / retry / delete / list / listFailed / stats / settings helpers
11
12
  - project OAuth/OIDC migration and OAuth client management
12
13
 
13
14
  ## Install
@@ -59,6 +60,18 @@ The current package focuses on:
59
60
  - `tasks.retry`
60
61
  - `tasks.wait`
61
62
  - `tasks.subscribe`
63
+ - `queue(name).send`
64
+ - `queue(name).receive`
65
+ - `queue(name).ack`
66
+ - `queue(name).release`
67
+ - `queue(name).fail`
68
+ - `queue(name).retry`
69
+ - `queue(name).delete`
70
+ - `queue(name).list`
71
+ - `queue(name).listFailed`
72
+ - `queue(name).stats`
73
+ - `queue(name).getSettings`
74
+ - `queue(name).updateSettings`
62
75
  - `auth.oauthServer.getStatus`
63
76
  - `auth.oauthServer.migrateToOidc`
64
77
  - `auth.oauthServer.getDiscovery`
@@ -75,6 +88,37 @@ The current package focuses on:
75
88
 
76
89
  This lets apps degrade gracefully when websocket or channel health is transient.
77
90
 
91
+ ## Queue Helpers
92
+
93
+ ```ts
94
+ const queue = supacloud.queue("emails");
95
+
96
+ const message = await queue.send(
97
+ { to: "user@example.com", template: "welcome" },
98
+ {
99
+ idempotencyKey: "welcome-user-123",
100
+ correlationId: "signup-123",
101
+ businessTaskId: "email-job-123",
102
+ metadata: { source: "signup" },
103
+ },
104
+ );
105
+
106
+ const leased = await queue.receive({ visibilityTimeoutSec: 60 });
107
+ if (leased) {
108
+ try {
109
+ await sendEmail(leased.payload);
110
+ await queue.ack(leased.id, { delivered: true });
111
+ } catch (error) {
112
+ await queue.release(leased.id, { delayMs: 30_000, error: String(error) });
113
+ }
114
+ }
115
+
116
+ const stats = await queue.stats();
117
+ console.log(stats.inFlight, stats.deadLettered);
118
+ ```
119
+
120
+ Queue conflicts such as replaying a non-DLQ message are surfaced as `SupaCloudApiError` with `status`, `code`, and `responseBody`, so callers do not need to parse raw `fetch` responses.
121
+
78
122
  ## OAuth/OIDC Helpers
79
123
 
80
124
  `client.auth.oauthServer` is the SupaCloud SDK surface for project-scoped OAuth 2.1 / OIDC migration and discovery.
package/dist/index.d.ts CHANGED
@@ -30,6 +30,9 @@ export type SupaCloudTaskDetail = {
30
30
  payload?: Record<string, unknown>;
31
31
  attempts?: SupaCloudTaskAttempt[];
32
32
  latest_logs?: SupaCloudTaskLogEntry[];
33
+ correlation_id?: string | null;
34
+ business_task_id?: string | null;
35
+ metadata?: Record<string, unknown> | null;
33
36
  updated_at?: string | null;
34
37
  created_at?: string | null;
35
38
  [key: string]: unknown;
@@ -56,12 +59,21 @@ export type SupaCloudTaskSubmitOptions = {
56
59
  timeoutSec?: number;
57
60
  idempotencyKey?: string;
58
61
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
62
+ /** Opaque correlation ID — the platform stores it but does not interpret it */
63
+ correlationId?: string;
64
+ /** Business-layer task ID for mapping back to the caller's own task table */
65
+ businessTaskId?: string;
66
+ /** Arbitrary JSON metadata — the platform stores it but does not interpret it */
67
+ metadata?: Record<string, unknown>;
59
68
  };
60
69
  export type SupaCloudQueueSendOptions = {
61
70
  delayMs?: number;
62
71
  maxAttempts?: number;
63
72
  idempotencyKey?: string;
64
73
  traceId?: string;
74
+ correlationId?: string;
75
+ businessTaskId?: string;
76
+ metadata?: Record<string, unknown>;
65
77
  };
66
78
  export type SupaCloudQueueReceiveOptions = {
67
79
  visibilityTimeoutSec?: number;
@@ -82,6 +94,24 @@ export type SupaCloudQueueListFilters = {
82
94
  export type SupaCloudQueueMessage = SupaCloudTaskDetail & {
83
95
  payload: Record<string, unknown>;
84
96
  };
97
+ export type SupaCloudQueueStats = {
98
+ pending: number;
99
+ leased: number;
100
+ running: number;
101
+ retryScheduled: number;
102
+ succeededLast24h: number;
103
+ failedLast24h: number;
104
+ deadLettered: number;
105
+ oldestPendingAgeSec: number | null;
106
+ inFlight: number;
107
+ };
108
+ export type SupaCloudQueueSettings = {
109
+ max_in_flight: number;
110
+ default_visibility_timeout_sec: number;
111
+ max_attempts: number;
112
+ rate_limit_per_minute: number;
113
+ };
114
+ export type SupaCloudQueueSettingsUpdate = Partial<SupaCloudQueueSettings>;
85
115
  export type SupaCloudTaskWaitOptions = {
86
116
  intervalMs?: number;
87
117
  signal?: AbortSignal;
@@ -183,7 +213,13 @@ export declare class SupaCloudTaskSubmitError extends Error {
183
213
  readonly responseBody: unknown;
184
214
  constructor(message: string, responseBody: unknown);
185
215
  }
186
- type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
216
+ export declare class SupaCloudApiError extends Error {
217
+ readonly status: number;
218
+ readonly code: string | null;
219
+ readonly responseBody: unknown;
220
+ constructor(message: string, status: number, responseBody: unknown);
221
+ }
222
+ type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
187
223
  declare class SupaCloudManagementClient<TClient extends SupabaseClient = SupabaseClient> {
188
224
  protected readonly options: Required<SupaCloudClientOptions<TClient>>;
189
225
  constructor(options: Required<SupaCloudClientOptions<TClient>>);
@@ -212,11 +248,15 @@ declare class SupaCloudQueueClient<TClient extends SupabaseClient = SupabaseClie
212
248
  receive(options?: SupaCloudQueueReceiveOptions): Promise<SupaCloudQueueMessage | null>;
213
249
  list(filters?: SupaCloudQueueListFilters): Promise<SupaCloudQueueMessage[]>;
214
250
  listFailed(limit?: number): Promise<SupaCloudQueueMessage[]>;
251
+ stats(): Promise<SupaCloudQueueStats>;
252
+ getSettings(): Promise<SupaCloudQueueSettings>;
253
+ updateSettings(settings: SupaCloudQueueSettingsUpdate): Promise<SupaCloudQueueSettings>;
215
254
  get(messageId: string): Promise<SupaCloudQueueMessage>;
216
255
  ack(messageId: string, result?: Record<string, unknown>): Promise<SupaCloudQueueMessage>;
217
256
  delete(messageId: string): Promise<void>;
218
257
  release(messageId: string, options?: SupaCloudQueueReleaseOptions): Promise<SupaCloudQueueMessage>;
219
258
  fail(messageId: string, options?: SupaCloudQueueFailOptions): Promise<SupaCloudQueueMessage>;
259
+ retry(messageId: string): Promise<SupaCloudQueueMessage>;
220
260
  }
221
261
  declare class SupaCloudOAuthServerClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
222
262
  getStatus(): Promise<SupaCloudOAuthServerStatus>;
package/dist/index.js CHANGED
@@ -7,6 +7,19 @@ class SupaCloudTaskSubmitError extends Error {
7
7
  this.responseBody = responseBody;
8
8
  }
9
9
  }
10
+
11
+ class SupaCloudApiError extends Error {
12
+ status;
13
+ code;
14
+ responseBody;
15
+ constructor(message, status, responseBody) {
16
+ super(message);
17
+ this.name = "SupaCloudApiError";
18
+ this.status = status;
19
+ this.responseBody = responseBody;
20
+ this.code = extractErrorCode(responseBody);
21
+ }
22
+ }
10
23
  var TERMINAL_STATUSES = new Set([
11
24
  "succeeded",
12
25
  "failed",
@@ -51,6 +64,22 @@ function createQueueQueryString(filters = {}) {
51
64
  const query = params.toString();
52
65
  return query.length > 0 ? `?${query}` : "";
53
66
  }
67
+ function extractErrorCode(body) {
68
+ if (!body || typeof body !== "object")
69
+ return null;
70
+ const code = body.code;
71
+ return typeof code === "string" ? code : null;
72
+ }
73
+ async function readResponseBody(response) {
74
+ const text = await response.text();
75
+ if (!text)
76
+ return;
77
+ try {
78
+ return JSON.parse(text);
79
+ } catch {
80
+ return text;
81
+ }
82
+ }
54
83
  async function defaultAccessTokenResolver(supabase) {
55
84
  const { data, error } = await supabase.auth.getSession();
56
85
  if (error)
@@ -91,12 +120,14 @@ class SupaCloudManagementClient {
91
120
  },
92
121
  ...body !== undefined ? { body: JSON.stringify(body) } : {}
93
122
  });
94
- if (!response.ok) {
95
- throw new Error(`SupaCloud request failed (${response.status})`);
96
- }
97
123
  if (response.status === 204)
98
124
  return;
99
- return await response.json();
125
+ const responseBody = await readResponseBody(response);
126
+ if (!response.ok) {
127
+ const message = responseBody && typeof responseBody === "object" && typeof responseBody.message === "string" ? String(responseBody.message) : `SupaCloud request failed (${response.status})`;
128
+ throw new SupaCloudApiError(message, response.status, responseBody);
129
+ }
130
+ return responseBody;
100
131
  }
101
132
  }
102
133
 
@@ -113,11 +144,18 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
113
144
  };
114
145
  }
115
146
  async submit(functionName, options = {}) {
116
- const { body, headers = {}, retries: _retries, timeoutSec: _timeoutSec, idempotencyKey: _idempotencyKey, method } = options;
147
+ const { body, headers = {}, retries: _retries, timeoutSec: _timeoutSec, idempotencyKey, method } = options;
148
+ const invokeHeaders = {
149
+ ...headers,
150
+ ...idempotencyKey ? { "x-supacloud-idempotency-key": idempotencyKey } : {},
151
+ ...options.correlationId ? { "x-supacloud-correlation-id": options.correlationId } : {},
152
+ ...options.businessTaskId ? { "x-supacloud-business-task-id": options.businessTaskId } : {},
153
+ ...options.metadata ? { "x-supacloud-task-metadata": JSON.stringify(options.metadata) } : {}
154
+ };
117
155
  const { data, error } = await this.options.supabase.functions.invoke(functionName, {
118
156
  body,
119
157
  method,
120
- headers
158
+ headers: invokeHeaders
121
159
  });
122
160
  if (error)
123
161
  throw error;
@@ -337,7 +375,10 @@ class SupaCloudQueueClient extends SupaCloudManagementClient {
337
375
  delayMs: options.delayMs,
338
376
  maxAttempts: options.maxAttempts,
339
377
  idempotencyKey: options.idempotencyKey,
340
- traceId: options.traceId
378
+ traceId: options.traceId,
379
+ correlationId: options.correlationId,
380
+ businessTaskId: options.businessTaskId,
381
+ metadata: options.metadata
341
382
  });
342
383
  }
343
384
  async receive(options = {}) {
@@ -350,6 +391,15 @@ class SupaCloudQueueClient extends SupaCloudManagementClient {
350
391
  async listFailed(limit = 100) {
351
392
  return this.list({ dlq: true, limit });
352
393
  }
394
+ async stats() {
395
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/stats`, "GET");
396
+ }
397
+ async getSettings() {
398
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/settings`, "GET");
399
+ }
400
+ async updateSettings(settings) {
401
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/settings`, "PATCH", settings);
402
+ }
353
403
  async get(messageId) {
354
404
  return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}`, "GET");
355
405
  }
@@ -365,6 +415,9 @@ class SupaCloudQueueClient extends SupaCloudManagementClient {
365
415
  async fail(messageId, options = {}) {
366
416
  return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}/fail`, "POST", options);
367
417
  }
418
+ async retry(messageId) {
419
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}/retry`, "POST");
420
+ }
368
421
  }
369
422
 
370
423
  class SupaCloudOAuthServerClient extends SupaCloudManagementClient {
@@ -458,5 +511,6 @@ function createSupaCloudClient(options) {
458
511
  }
459
512
  export {
460
513
  createSupaCloudClient,
461
- SupaCloudTaskSubmitError
514
+ SupaCloudTaskSubmitError,
515
+ SupaCloudApiError
462
516
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supacloud/js",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "Platform SDK for SupaCloud, built on top of supabase-js",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",