@supacloud/js 0.15.1 → 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 +57 -7
- 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
|
|
|
@@ -116,7 +147,10 @@ class SupaCloudTasksClient extends SupaCloudManagementClient {
|
|
|
116
147
|
const { body, headers = {}, retries: _retries, timeoutSec: _timeoutSec, idempotencyKey, method } = options;
|
|
117
148
|
const invokeHeaders = {
|
|
118
149
|
...headers,
|
|
119
|
-
...idempotencyKey ? { "x-supacloud-idempotency-key": idempotencyKey } : {}
|
|
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) } : {}
|
|
120
154
|
};
|
|
121
155
|
const { data, error } = await this.options.supabase.functions.invoke(functionName, {
|
|
122
156
|
body,
|
|
@@ -341,7 +375,10 @@ class SupaCloudQueueClient extends SupaCloudManagementClient {
|
|
|
341
375
|
delayMs: options.delayMs,
|
|
342
376
|
maxAttempts: options.maxAttempts,
|
|
343
377
|
idempotencyKey: options.idempotencyKey,
|
|
344
|
-
traceId: options.traceId
|
|
378
|
+
traceId: options.traceId,
|
|
379
|
+
correlationId: options.correlationId,
|
|
380
|
+
businessTaskId: options.businessTaskId,
|
|
381
|
+
metadata: options.metadata
|
|
345
382
|
});
|
|
346
383
|
}
|
|
347
384
|
async receive(options = {}) {
|
|
@@ -354,6 +391,15 @@ class SupaCloudQueueClient extends SupaCloudManagementClient {
|
|
|
354
391
|
async listFailed(limit = 100) {
|
|
355
392
|
return this.list({ dlq: true, limit });
|
|
356
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
|
+
}
|
|
357
403
|
async get(messageId) {
|
|
358
404
|
return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}`, "GET");
|
|
359
405
|
}
|
|
@@ -369,6 +415,9 @@ class SupaCloudQueueClient extends SupaCloudManagementClient {
|
|
|
369
415
|
async fail(messageId, options = {}) {
|
|
370
416
|
return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}/fail`, "POST", options);
|
|
371
417
|
}
|
|
418
|
+
async retry(messageId) {
|
|
419
|
+
return this.request(`/v1/projects/${this.options.projectRef}/tasks/queues/${this.encodedName}/messages/${messageId}/retry`, "POST");
|
|
420
|
+
}
|
|
372
421
|
}
|
|
373
422
|
|
|
374
423
|
class SupaCloudOAuthServerClient extends SupaCloudManagementClient {
|
|
@@ -462,5 +511,6 @@ function createSupaCloudClient(options) {
|
|
|
462
511
|
}
|
|
463
512
|
export {
|
|
464
513
|
createSupaCloudClient,
|
|
465
|
-
SupaCloudTaskSubmitError
|
|
514
|
+
SupaCloudTaskSubmitError,
|
|
515
|
+
SupaCloudApiError
|
|
466
516
|
};
|