@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 +44 -0
- package/dist/index.d.ts +41 -1
- package/dist/index.js +62 -8
- package/package.json +1 -1
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
};
|