@supacloud/js 0.11.3 → 0.12.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/dist/index.d.ts CHANGED
@@ -57,6 +57,31 @@ export type SupaCloudTaskSubmitOptions = {
57
57
  idempotencyKey?: string;
58
58
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
59
59
  };
60
+ export type SupaCloudQueueSendOptions = {
61
+ delayMs?: number;
62
+ maxAttempts?: number;
63
+ idempotencyKey?: string;
64
+ traceId?: string;
65
+ };
66
+ export type SupaCloudQueueReceiveOptions = {
67
+ visibilityTimeoutSec?: number;
68
+ };
69
+ export type SupaCloudQueueReleaseOptions = {
70
+ delayMs?: number;
71
+ error?: string;
72
+ };
73
+ export type SupaCloudQueueFailOptions = {
74
+ error?: string;
75
+ deadLetter?: boolean;
76
+ };
77
+ export type SupaCloudQueueListFilters = {
78
+ status?: string | string[];
79
+ dlq?: boolean;
80
+ limit?: number;
81
+ };
82
+ export type SupaCloudQueueMessage = SupaCloudTaskDetail & {
83
+ payload: Record<string, unknown>;
84
+ };
60
85
  export type SupaCloudTaskWaitOptions = {
61
86
  intervalMs?: number;
62
87
  signal?: AbortSignal;
@@ -64,6 +89,8 @@ export type SupaCloudTaskWaitOptions = {
64
89
  export type SupaCloudTaskSubscribeState = "connecting" | "realtime" | "polling" | "closed";
65
90
  export type SupaCloudTaskSubscribeOptions = {
66
91
  pollingIntervalMs?: number;
92
+ realtimeTimeoutMs?: number;
93
+ reconcileIntervalMs?: number;
67
94
  onUpdate: (task: SupaCloudTaskSnapshot) => void;
68
95
  onStateChange?: (state: SupaCloudTaskSubscribeState, details?: {
69
96
  error?: unknown;
@@ -94,11 +121,14 @@ export declare class SupaCloudTaskSubmitError extends Error {
94
121
  readonly responseBody: unknown;
95
122
  constructor(message: string, responseBody: unknown);
96
123
  }
97
- declare class SupaCloudTasksClient<TClient extends SupabaseClient = SupabaseClient> {
98
- private readonly options;
124
+ type HttpMethod = "GET" | "POST" | "DELETE";
125
+ declare class SupaCloudManagementClient<TClient extends SupabaseClient = SupabaseClient> {
126
+ protected readonly options: Required<SupaCloudClientOptions<TClient>>;
99
127
  constructor(options: Required<SupaCloudClientOptions<TClient>>);
100
- private resolveAccessToken;
101
- private request;
128
+ protected resolveAccessToken(): Promise<string>;
129
+ protected request<T>(path: string, method: HttpMethod, body?: unknown): Promise<T>;
130
+ }
131
+ declare class SupaCloudTasksClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
102
132
  private createReceipt;
103
133
  submit(functionName: string, options?: SupaCloudTaskSubmitOptions): Promise<SupaCloudTaskReceipt>;
104
134
  get(taskId: string): Promise<SupaCloudTaskDetail>;
@@ -112,11 +142,26 @@ declare class SupaCloudTasksClient<TClient extends SupabaseClient = SupabaseClie
112
142
  unsubscribe(): void;
113
143
  };
114
144
  }
145
+ declare class SupaCloudQueueClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
146
+ private readonly name;
147
+ constructor(options: Required<SupaCloudClientOptions<TClient>>, name: string);
148
+ private get encodedName();
149
+ send(payload?: Record<string, unknown>, options?: SupaCloudQueueSendOptions): Promise<SupaCloudQueueMessage>;
150
+ receive(options?: SupaCloudQueueReceiveOptions): Promise<SupaCloudQueueMessage | null>;
151
+ list(filters?: SupaCloudQueueListFilters): Promise<SupaCloudQueueMessage[]>;
152
+ listFailed(limit?: number): Promise<SupaCloudQueueMessage[]>;
153
+ get(messageId: string): Promise<SupaCloudQueueMessage>;
154
+ ack(messageId: string, result?: Record<string, unknown>): Promise<SupaCloudQueueMessage>;
155
+ delete(messageId: string): Promise<void>;
156
+ release(messageId: string, options?: SupaCloudQueueReleaseOptions): Promise<SupaCloudQueueMessage>;
157
+ fail(messageId: string, options?: SupaCloudQueueFailOptions): Promise<SupaCloudQueueMessage>;
158
+ }
115
159
  export declare function createSupaCloudClient<TClient extends SupabaseClient = SupabaseClient>(options: SupaCloudClientOptions<TClient>): {
116
160
  supabase: TClient;
117
161
  projectRef: string;
118
162
  managementApiUrl: string;
119
163
  tasks: SupaCloudTasksClient<TClient>;
164
+ queue: (name: string) => SupaCloudQueueClient<TClient>;
120
165
  functions: {
121
166
  invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt>;
122
167
  };
package/dist/index.js CHANGED
@@ -39,6 +39,18 @@ function createQueryString(filters = {}) {
39
39
  const query = params.toString();
40
40
  return query.length > 0 ? `?${query}` : "";
41
41
  }
42
+ function createQueueQueryString(filters = {}) {
43
+ const params = new URLSearchParams;
44
+ const statuses = toArray(filters.status);
45
+ if (statuses?.length)
46
+ params.set("status", statuses.join(","));
47
+ if (filters.dlq)
48
+ params.set("dlq", "true");
49
+ if (filters.limit !== undefined)
50
+ params.set("limit", String(filters.limit));
51
+ const query = params.toString();
52
+ return query.length > 0 ? `?${query}` : "";
53
+ }
42
54
  async function defaultAccessTokenResolver(supabase) {
43
55
  const { data, error } = await supabase.auth.getSession();
44
56
  if (error)
@@ -57,7 +69,7 @@ function normalizeTaskSnapshot(task) {
57
69
  };
58
70
  }
59
71
 
60
- class SupaCloudTasksClient {
72
+ class SupaCloudManagementClient {
61
73
  options;
62
74
  constructor(options) {
63
75
  this.options = options;
@@ -82,8 +94,13 @@ class SupaCloudTasksClient {
82
94
  if (!response.ok) {
83
95
  throw new Error(`SupaCloud request failed (${response.status})`);
84
96
  }
97
+ if (response.status === 204)
98
+ return;
85
99
  return await response.json();
86
100
  }
101
+ }
102
+
103
+ class SupaCloudTasksClient extends SupaCloudManagementClient {
87
104
  createReceipt(taskId, status) {
88
105
  return {
89
106
  taskId,
@@ -152,8 +169,12 @@ class SupaCloudTasksClient {
152
169
  let closed = false;
153
170
  let channel = null;
154
171
  let pollTimer = null;
172
+ let realtimeTimeoutTimer = null;
173
+ let reconcileTimer = null;
155
174
  let mode = "connecting";
156
175
  const pollingIntervalMs = options.pollingIntervalMs ?? this.options.pollingIntervalMs;
176
+ const realtimeTimeoutMs = options.realtimeTimeoutMs ?? 1e4;
177
+ const reconcileIntervalMs = options.reconcileIntervalMs ?? Math.max(30000, pollingIntervalMs * 10);
157
178
  const stopOnTerminal = options.stopOnTerminal ?? true;
158
179
  const setMode = (next, details) => {
159
180
  if (closed || mode === next)
@@ -167,6 +188,18 @@ class SupaCloudTasksClient {
167
188
  pollTimer = null;
168
189
  }
169
190
  };
191
+ const stopRealtimeTimeout = () => {
192
+ if (realtimeTimeoutTimer) {
193
+ clearTimeout(realtimeTimeoutTimer);
194
+ realtimeTimeoutTimer = null;
195
+ }
196
+ };
197
+ const stopReconcile = () => {
198
+ if (reconcileTimer) {
199
+ clearTimeout(reconcileTimer);
200
+ reconcileTimer = null;
201
+ }
202
+ };
170
203
  const teardownRealtime = async () => {
171
204
  if (channel) {
172
205
  const current = channel;
@@ -178,6 +211,8 @@ class SupaCloudTasksClient {
178
211
  if (closed)
179
212
  return;
180
213
  stopPolling();
214
+ stopRealtimeTimeout();
215
+ stopReconcile();
181
216
  await teardownRealtime();
182
217
  setMode("closed");
183
218
  closed = true;
@@ -205,10 +240,35 @@ class SupaCloudTasksClient {
205
240
  }
206
241
  }
207
242
  };
243
+ const reconcileOnce = async () => {
244
+ if (closed || mode !== "realtime")
245
+ return;
246
+ try {
247
+ emitTask(await this.get(taskId));
248
+ } catch (error) {
249
+ options.onError?.(error);
250
+ } finally {
251
+ if (!closed && mode === "realtime") {
252
+ reconcileTimer = setTimeout(() => {
253
+ reconcileOnce();
254
+ }, reconcileIntervalMs);
255
+ }
256
+ }
257
+ };
258
+ const startReconcile = () => {
259
+ if (closed || reconcileIntervalMs <= 0)
260
+ return;
261
+ stopReconcile();
262
+ reconcileTimer = setTimeout(() => {
263
+ reconcileOnce();
264
+ }, reconcileIntervalMs);
265
+ };
208
266
  const startPolling = (error) => {
209
267
  if (closed)
210
268
  return;
211
269
  stopPolling();
270
+ stopRealtimeTimeout();
271
+ stopReconcile();
212
272
  setMode("polling", { error });
213
273
  pollOnce();
214
274
  };
@@ -226,12 +286,14 @@ class SupaCloudTasksClient {
226
286
  return;
227
287
  if (status === "SUBSCRIBED") {
228
288
  stopPolling();
289
+ stopRealtimeTimeout();
229
290
  setMode("realtime");
230
291
  try {
231
292
  emitTask(await this.get(taskId));
232
293
  } catch (err) {
233
294
  options.onError?.(err);
234
295
  }
296
+ startReconcile();
235
297
  return;
236
298
  }
237
299
  if (status === "TIMED_OUT" || status === "CHANNEL_ERROR" || status === "CLOSED") {
@@ -239,6 +301,15 @@ class SupaCloudTasksClient {
239
301
  startPolling(error);
240
302
  }
241
303
  });
304
+ if (realtimeTimeoutMs > 0) {
305
+ realtimeTimeoutTimer = setTimeout(() => {
306
+ if (!closed && mode === "connecting") {
307
+ teardownRealtime().finally(() => {
308
+ startPolling(new Error("SupaCloud Realtime subscription timed out"));
309
+ });
310
+ }
311
+ }, realtimeTimeoutMs);
312
+ }
242
313
  setMode("connecting");
243
314
  return {
244
315
  get connectionState() {
@@ -250,6 +321,51 @@ class SupaCloudTasksClient {
250
321
  };
251
322
  }
252
323
  }
324
+
325
+ class SupaCloudQueueClient extends SupaCloudManagementClient {
326
+ name;
327
+ constructor(options, name) {
328
+ super(options);
329
+ this.name = name;
330
+ }
331
+ get encodedName() {
332
+ return encodeURIComponent(this.name);
333
+ }
334
+ async send(payload = {}, options = {}) {
335
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages`, "POST", {
336
+ payload,
337
+ delayMs: options.delayMs,
338
+ maxAttempts: options.maxAttempts,
339
+ idempotencyKey: options.idempotencyKey,
340
+ traceId: options.traceId
341
+ });
342
+ }
343
+ async receive(options = {}) {
344
+ const message = await this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/receive`, "POST", options);
345
+ return message ?? null;
346
+ }
347
+ async list(filters = {}) {
348
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages${createQueueQueryString(filters)}`, "GET");
349
+ }
350
+ async listFailed(limit = 100) {
351
+ return this.list({ dlq: true, limit });
352
+ }
353
+ async get(messageId) {
354
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}`, "GET");
355
+ }
356
+ async ack(messageId, result) {
357
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}/ack`, "POST", result ? { result } : {});
358
+ }
359
+ async delete(messageId) {
360
+ await this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}`, "DELETE");
361
+ }
362
+ async release(messageId, options = {}) {
363
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}/release`, "POST", options);
364
+ }
365
+ async fail(messageId, options = {}) {
366
+ return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}/fail`, "POST", options);
367
+ }
368
+ }
253
369
  function createSupaCloudClient(options) {
254
370
  const normalized = {
255
371
  ...options,
@@ -263,6 +379,7 @@ function createSupaCloudClient(options) {
263
379
  projectRef: normalized.projectRef,
264
380
  managementApiUrl: normalized.managementApiUrl,
265
381
  tasks,
382
+ queue: (name) => new SupaCloudQueueClient(normalized, name),
266
383
  functions: {
267
384
  invokeBackground: (functionName, submitOptions) => tasks.submit(functionName, submitOptions)
268
385
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supacloud/js",
3
- "version": "0.11.3",
3
+ "version": "0.12.0",
4
4
  "description": "Platform SDK for SupaCloud, built on top of supabase-js",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",