@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 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
@@ -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 fetch(`${this.baseUrl}${path}`, {
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 fetch(`${base}/v1/auth/github-oidc`, {
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 }),
@@ -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 fetch(`${this.baseUrl}${path}`, {
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 fetch(`${base}/v1/auth/github-oidc`, {
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.0",
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",