@novence/sdk 0.6.0 → 0.6.1
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 +8 -0
- package/dist/cjs/index.d.ts +18 -0
- package/dist/cjs/index.js +43 -3
- package/dist/esm/index.d.ts +18 -0
- package/dist/esm/index.js +42 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -143,6 +143,14 @@ call at a different control plane — useful when running the API locally.
|
|
|
143
143
|
| `client.account` | `get` · `consoleKit` · `createSession` · `revokeSession` |
|
|
144
144
|
| `client.apiKeys` | `revoke` |
|
|
145
145
|
|
|
146
|
+
### Rate limits
|
|
147
|
+
|
|
148
|
+
The API allows about 100 requests per 10 seconds per IP. When a call gets HTTP 429 with
|
|
149
|
+
a short `Retry-After` (30 seconds or less), the SDK waits and sends it again, up to 5
|
|
150
|
+
times, so a large `uploadDir` finishes instead of failing partway. Longer limits (hourly
|
|
151
|
+
caps) are thrown at once as a `NovenceError` with `status: 429`. Tune or disable with
|
|
152
|
+
the exported `rateLimitRetry` (`rateLimitRetry.maxRetries = 0`).
|
|
153
|
+
|
|
146
154
|
### Deploy from a GitHub repo (optional)
|
|
147
155
|
|
|
148
156
|
```ts
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
/** Public control plane. */
|
|
2
2
|
export declare const DEFAULT_BASE_URL = "https://api.novence.ai";
|
|
3
|
+
/**
|
|
4
|
+
* How the SDK handles HTTP 429. The API allows about 100 requests per 10 seconds per IP,
|
|
5
|
+
* and a large directory upload from a shared CI runner can exceed that. A 429 means the
|
|
6
|
+
* request was not processed, so it is safe to send again.
|
|
7
|
+
*
|
|
8
|
+
* Mutable on purpose: set `rateLimitRetry.maxRetries = 0` to turn retries off.
|
|
9
|
+
*/
|
|
10
|
+
export declare const rateLimitRetry: {
|
|
11
|
+
/** Extra attempts after the first 429. */
|
|
12
|
+
maxRetries: number;
|
|
13
|
+
/**
|
|
14
|
+
* Longest `Retry-After` worth waiting for, in seconds. Hourly limits (too many
|
|
15
|
+
* sign-ups, too many data writes) answer with a longer wait and are returned to the
|
|
16
|
+
* caller at once instead.
|
|
17
|
+
*/
|
|
18
|
+
maxWaitSeconds: number;
|
|
19
|
+
sleep: (ms: number) => Promise<void>;
|
|
20
|
+
};
|
|
3
21
|
/** True for a Novence client from any copy of this module. */
|
|
4
22
|
export declare function isNovenceClient(value: unknown): value is Novence;
|
|
5
23
|
/**
|
package/dist/cjs/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.Novence = exports.CONSOLE_INJECT_MARKER = exports.NovenceError = exports.DEFAULT_BASE_URL = void 0;
|
|
3
|
+
exports.Novence = exports.CONSOLE_INJECT_MARKER = exports.NovenceError = exports.rateLimitRetry = exports.DEFAULT_BASE_URL = void 0;
|
|
4
4
|
exports.isNovenceClient = isNovenceClient;
|
|
5
5
|
exports.exchangeGithubOidc = exchangeGithubOidc;
|
|
6
6
|
exports.bootstrapAccount = bootstrapAccount;
|
|
@@ -24,6 +24,46 @@ function resolveBaseUrl(explicit) {
|
|
|
24
24
|
const raw = explicit ?? process.env.NOVENCE_BASE_URL ?? exports.DEFAULT_BASE_URL;
|
|
25
25
|
return raw.replace(/\/$/, "");
|
|
26
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* How the SDK handles HTTP 429. The API allows about 100 requests per 10 seconds per IP,
|
|
29
|
+
* and a large directory upload from a shared CI runner can exceed that. A 429 means the
|
|
30
|
+
* request was not processed, so it is safe to send again.
|
|
31
|
+
*
|
|
32
|
+
* Mutable on purpose: set `rateLimitRetry.maxRetries = 0` to turn retries off.
|
|
33
|
+
*/
|
|
34
|
+
exports.rateLimitRetry = {
|
|
35
|
+
/** Extra attempts after the first 429. */
|
|
36
|
+
maxRetries: 5,
|
|
37
|
+
/**
|
|
38
|
+
* Longest `Retry-After` worth waiting for, in seconds. Hourly limits (too many
|
|
39
|
+
* sign-ups, too many data writes) answer with a longer wait and are returned to the
|
|
40
|
+
* caller at once instead.
|
|
41
|
+
*/
|
|
42
|
+
maxWaitSeconds: 30,
|
|
43
|
+
sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
|
|
44
|
+
};
|
|
45
|
+
/** Seconds to wait before retrying a 429, or null when the caller should get the error. */
|
|
46
|
+
function retryDelaySeconds(res, attempt) {
|
|
47
|
+
if (res.status !== 429 || attempt >= exports.rateLimitRetry.maxRetries)
|
|
48
|
+
return null;
|
|
49
|
+
const header = Number(res.headers.get("retry-after"));
|
|
50
|
+
// No usable header: back off 1, 2, 4, 8… seconds.
|
|
51
|
+
const seconds = Number.isFinite(header) && header > 0 ? header : 2 ** attempt;
|
|
52
|
+
return seconds <= exports.rateLimitRetry.maxWaitSeconds ? seconds : null;
|
|
53
|
+
}
|
|
54
|
+
/** `fetch` that waits out short rate limits. `init` must be replayable (string body). */
|
|
55
|
+
async function fetchWithRateLimitRetry(url, init) {
|
|
56
|
+
for (let attempt = 0;; attempt += 1) {
|
|
57
|
+
const res = await fetch(url, init);
|
|
58
|
+
const wait = retryDelaySeconds(res, attempt);
|
|
59
|
+
if (wait === null)
|
|
60
|
+
return res;
|
|
61
|
+
// Free the connection before sleeping; the body of a 429 says nothing we need.
|
|
62
|
+
await res.body?.cancel().catch(() => undefined);
|
|
63
|
+
// A little jitter so parallel jobs behind one IP do not all come back together.
|
|
64
|
+
await exports.rateLimitRetry.sleep(Math.round(wait * 1000 + Math.random() * 250));
|
|
65
|
+
}
|
|
66
|
+
}
|
|
27
67
|
/**
|
|
28
68
|
* Brand for cross-copy identity checks.
|
|
29
69
|
*
|
|
@@ -104,7 +144,7 @@ class Novence {
|
|
|
104
144
|
});
|
|
105
145
|
}
|
|
106
146
|
async request(method, path, body) {
|
|
107
|
-
const res = await
|
|
147
|
+
const res = await fetchWithRateLimitRetry(`${this.baseUrl}${path}`, {
|
|
108
148
|
method,
|
|
109
149
|
headers: {
|
|
110
150
|
Authorization: `Bearer ${this.apiKey}`,
|
|
@@ -404,7 +444,7 @@ async function exchangeGithubOidc(opts = {}) {
|
|
|
404
444
|
if (!tokenRes.ok || !tokenBody.value) {
|
|
405
445
|
throw new NovenceError(`GitHub did not issue an OIDC token (HTTP ${tokenRes.status}).`, tokenRes.status || 500, undefined, "oidc_unavailable");
|
|
406
446
|
}
|
|
407
|
-
const res = await
|
|
447
|
+
const res = await fetchWithRateLimitRetry(`${base}/v1/auth/github-oidc`, {
|
|
408
448
|
method: "POST",
|
|
409
449
|
headers: { "Content-Type": "application/json" },
|
|
410
450
|
body: JSON.stringify({ token: tokenBody.value, projectId: opts.projectId }),
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
/** Public control plane. */
|
|
2
2
|
export declare const DEFAULT_BASE_URL = "https://api.novence.ai";
|
|
3
|
+
/**
|
|
4
|
+
* How the SDK handles HTTP 429. The API allows about 100 requests per 10 seconds per IP,
|
|
5
|
+
* and a large directory upload from a shared CI runner can exceed that. A 429 means the
|
|
6
|
+
* request was not processed, so it is safe to send again.
|
|
7
|
+
*
|
|
8
|
+
* Mutable on purpose: set `rateLimitRetry.maxRetries = 0` to turn retries off.
|
|
9
|
+
*/
|
|
10
|
+
export declare const rateLimitRetry: {
|
|
11
|
+
/** Extra attempts after the first 429. */
|
|
12
|
+
maxRetries: number;
|
|
13
|
+
/**
|
|
14
|
+
* Longest `Retry-After` worth waiting for, in seconds. Hourly limits (too many
|
|
15
|
+
* sign-ups, too many data writes) answer with a longer wait and are returned to the
|
|
16
|
+
* caller at once instead.
|
|
17
|
+
*/
|
|
18
|
+
maxWaitSeconds: number;
|
|
19
|
+
sleep: (ms: number) => Promise<void>;
|
|
20
|
+
};
|
|
3
21
|
/** True for a Novence client from any copy of this module. */
|
|
4
22
|
export declare function isNovenceClient(value: unknown): value is Novence;
|
|
5
23
|
/**
|
package/dist/esm/index.js
CHANGED
|
@@ -11,6 +11,46 @@ function resolveBaseUrl(explicit) {
|
|
|
11
11
|
const raw = explicit ?? process.env.NOVENCE_BASE_URL ?? DEFAULT_BASE_URL;
|
|
12
12
|
return raw.replace(/\/$/, "");
|
|
13
13
|
}
|
|
14
|
+
/**
|
|
15
|
+
* How the SDK handles HTTP 429. The API allows about 100 requests per 10 seconds per IP,
|
|
16
|
+
* and a large directory upload from a shared CI runner can exceed that. A 429 means the
|
|
17
|
+
* request was not processed, so it is safe to send again.
|
|
18
|
+
*
|
|
19
|
+
* Mutable on purpose: set `rateLimitRetry.maxRetries = 0` to turn retries off.
|
|
20
|
+
*/
|
|
21
|
+
export const rateLimitRetry = {
|
|
22
|
+
/** Extra attempts after the first 429. */
|
|
23
|
+
maxRetries: 5,
|
|
24
|
+
/**
|
|
25
|
+
* Longest `Retry-After` worth waiting for, in seconds. Hourly limits (too many
|
|
26
|
+
* sign-ups, too many data writes) answer with a longer wait and are returned to the
|
|
27
|
+
* caller at once instead.
|
|
28
|
+
*/
|
|
29
|
+
maxWaitSeconds: 30,
|
|
30
|
+
sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
|
|
31
|
+
};
|
|
32
|
+
/** Seconds to wait before retrying a 429, or null when the caller should get the error. */
|
|
33
|
+
function retryDelaySeconds(res, attempt) {
|
|
34
|
+
if (res.status !== 429 || attempt >= rateLimitRetry.maxRetries)
|
|
35
|
+
return null;
|
|
36
|
+
const header = Number(res.headers.get("retry-after"));
|
|
37
|
+
// No usable header: back off 1, 2, 4, 8… seconds.
|
|
38
|
+
const seconds = Number.isFinite(header) && header > 0 ? header : 2 ** attempt;
|
|
39
|
+
return seconds <= rateLimitRetry.maxWaitSeconds ? seconds : null;
|
|
40
|
+
}
|
|
41
|
+
/** `fetch` that waits out short rate limits. `init` must be replayable (string body). */
|
|
42
|
+
async function fetchWithRateLimitRetry(url, init) {
|
|
43
|
+
for (let attempt = 0;; attempt += 1) {
|
|
44
|
+
const res = await fetch(url, init);
|
|
45
|
+
const wait = retryDelaySeconds(res, attempt);
|
|
46
|
+
if (wait === null)
|
|
47
|
+
return res;
|
|
48
|
+
// Free the connection before sleeping; the body of a 429 says nothing we need.
|
|
49
|
+
await res.body?.cancel().catch(() => undefined);
|
|
50
|
+
// A little jitter so parallel jobs behind one IP do not all come back together.
|
|
51
|
+
await rateLimitRetry.sleep(Math.round(wait * 1000 + Math.random() * 250));
|
|
52
|
+
}
|
|
53
|
+
}
|
|
14
54
|
/**
|
|
15
55
|
* Brand for cross-copy identity checks.
|
|
16
56
|
*
|
|
@@ -90,7 +130,7 @@ export class Novence {
|
|
|
90
130
|
});
|
|
91
131
|
}
|
|
92
132
|
async request(method, path, body) {
|
|
93
|
-
const res = await
|
|
133
|
+
const res = await fetchWithRateLimitRetry(`${this.baseUrl}${path}`, {
|
|
94
134
|
method,
|
|
95
135
|
headers: {
|
|
96
136
|
Authorization: `Bearer ${this.apiKey}`,
|
|
@@ -389,7 +429,7 @@ export async function exchangeGithubOidc(opts = {}) {
|
|
|
389
429
|
if (!tokenRes.ok || !tokenBody.value) {
|
|
390
430
|
throw new NovenceError(`GitHub did not issue an OIDC token (HTTP ${tokenRes.status}).`, tokenRes.status || 500, undefined, "oidc_unavailable");
|
|
391
431
|
}
|
|
392
|
-
const res = await
|
|
432
|
+
const res = await fetchWithRateLimitRetry(`${base}/v1/auth/github-oidc`, {
|
|
393
433
|
method: "POST",
|
|
394
434
|
headers: { "Content-Type": "application/json" },
|
|
395
435
|
body: JSON.stringify({ token: tokenBody.value, projectId: opts.projectId }),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@novence/sdk",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.1",
|
|
4
4
|
"description": "Official TypeScript SDK for Novence — static site hosting for AI agents. Create projects, upload files, run quality checks, deploy to the edge.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|