@novence/sdk 0.4.0 → 0.6.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 CHANGED
@@ -40,6 +40,11 @@ console.log(url); // https://{suffix}.novence.ai
40
40
 
41
41
  One HTML document (report, dashboard, artifact): `client.publishHtml({ html, title })` then poll `deployments.latest`. CLI: `npx novence deploy report.html`.
42
42
 
43
+ > **Behaviour change in 0.6.0:** `files.uploadDir` now makes the project's files match
44
+ > the directory. Files it no longer has are removed (`/data/*.json` is kept), and
45
+ > `.well-known/` is uploaded. Pass `{ prune: false }` for the old add-only behaviour.
46
+ > It returns `{ uploaded, removed, kept }`.
47
+
43
48
  ### Bootstrap + verify (email path)
44
49
 
45
50
  When you need a key from email OTP instead of the CLI:
@@ -80,6 +85,9 @@ if (deployment.status === "live") {
80
85
  `deployment.status` is a union — `pending | queued | checking | promoting | live | failed`
81
86
  — so the compiler catches typos in status comparisons.
82
87
 
88
+ A deploy takes about 20 seconds with a check runner warm and 1–2 minutes from cold. Every
89
+ deploy ends in `live` or `failed`: at the latest after 15 minutes without a runner or 10 in checks.
90
+
83
91
  ### Checks
84
92
 
85
93
  `deployment.checksResults` carries the quality gate. When `skipped` is true
@@ -94,6 +102,13 @@ if (checks?.skipped) {
94
102
  }
95
103
  ```
96
104
 
105
+ Checks score the files in this deployment before anything goes live, so a rejected
106
+ deploy leaves the live site as it was. `checks.measurementError` is set when the page
107
+ could not be scored; that deploy fails.
108
+
109
+ `deployments.rollback(projectId)` restores the version live immediately before the
110
+ current one, so rolling back twice is an undo. Pass `{ deploymentId }` to go further back.
111
+
97
112
  Every method returns a typed response. `Project`, `Deployment`, `ChecksResults`,
98
113
  `Form`, `Quotas`, `Analytics`, `StagingFile` and the rest are exported for your own
99
114
  signatures:
@@ -119,17 +134,46 @@ call at a different control plane — useful when running the API locally.
119
134
  | Namespace | Methods |
120
135
  | --- | --- |
121
136
  | `client.projects` | `create` · `list` · `get` · `update` · `usage` · `analytics` · `brief` · `putBrief` · `events` |
122
- | `client.files` | `uploadDir` · `uploadBuffer` · `getUploadUrl` · `getUploadUrlsBatch` · `confirm` · `confirmBatch` |
123
- | `client.deployments` | `create` · `latest` |
137
+ | `client.files` | `uploadDir` · `uploadBuffer` · `list` · `delete` · `getUploadUrl` · `getUploadUrlsBatch` · `confirm` · `confirmBatch` |
138
+ | `client.deployments` | `create` · `latest` · `rollback` |
139
+ | `client.git` | `connect` · `get` · `disconnect` |
124
140
  | `client.domains` | `configure` · `status` |
125
141
  | `client.forms` | `create` · `list` · `get` · `update` · `delete` · `listSubmissions` · `deleteSubmission` |
126
- | `client.billing` | `quotas` · `checkout` · `portal` · `mppUpgrade` |
142
+ | `client.billing` | `quotas` · `spendLimit` · `setSpendLimit` · `checkout` · `portal` · `mppUpgrade` |
127
143
  | `client.account` | `get` · `consoleKit` · `createSession` · `revokeSession` |
128
144
  | `client.apiKeys` | `revoke` |
129
145
 
146
+ ### Deploy from a GitHub repo (optional)
147
+
148
+ ```ts
149
+ const { connection } = await client.git.connect(project.id, { repository: "owner/name", branch: "main" });
150
+ // Write connection.workflow to .github/workflows/novence.yml, add your build step, commit and push.
151
+ ```
152
+
153
+ Pushes to that branch then deploy. The workflow signs in with GitHub OIDC, so no API key
154
+ is stored in the repository; Novence does not clone or build it. Inside such a job,
155
+ `exchangeGithubOidc()` returns a 30-minute key that can only upload to and deploy that
156
+ project. Each `Deployment` carries a `source` (commit, ref, repository for git deploys).
157
+ A deploy requested while another is running comes back with `queuedRedeploy: true` and
158
+ starts by itself afterwards: keep polling `deployments.latest` for a new id.
159
+
130
160
  Standalone helpers for the pre-auth flow: `createDemoAccount`, `claimAccount`,
131
161
  `bootstrapAccount`, `verifyEmail`, `resendVerification`, `reissueApiKey`.
132
162
 
163
+ ## Spend limit
164
+
165
+ Cap monthly overage on Pro/Scale. At the cap, anything that would add overage pauses —
166
+ including live sites once bandwidth is past the included pool — until you raise it or the
167
+ UTC month resets. A request blocked by the cap throws `NovenceError` with `status` 402 and
168
+ `wall` `"spend_limit"`.
169
+
170
+ ```ts
171
+ await client.billing.setSpendLimit(50); // $50/month; 0 = never pay overage
172
+ const s = await client.billing.spendLimit();
173
+ // { limitUsd: 50, overageUsd: 12.4, usedPct: 24, reached: false, paused: [], … }
174
+ await client.billing.setSpendLimit(null); // remove the cap
175
+ ```
176
+
133
177
  ## Identity checks
134
178
 
135
179
  Prefer `isNovenceClient()` over `instanceof Novence`:
@@ -8,7 +8,14 @@ export declare function isNovenceClient(value: unknown): value is Novence;
8
8
  */
9
9
  export declare class NovenceError extends Error {
10
10
  readonly status: number;
11
- constructor(message: string, status: number);
11
+ /**
12
+ * On a 402, which wall was hit: `verify` (email OTP), `upgrade` (Checkout/MPP), or
13
+ * `spend_limit` (the account's own overage cap — raise it with billing.setSpendLimit).
14
+ */
15
+ readonly wall?: string;
16
+ /** Machine-readable reason when the API sends one, e.g. `repo_not_connected`. */
17
+ readonly code?: string;
18
+ constructor(message: string, status: number, wall?: string, code?: string);
12
19
  }
13
20
  export interface NovenceOptions {
14
21
  apiKey: string;
@@ -74,11 +81,70 @@ export interface ChecksResults {
74
81
  reason?: string;
75
82
  /** Non-blocking findings, e.g. low Lighthouse performance while `enforcePerformance` is off. */
76
83
  warnings?: string[];
84
+ /** The deployment these results were measured from. */
85
+ deploymentId?: string;
86
+ /** Why the page could not be scored. The deploy fails and `lighthouse` is null. */
87
+ measurementError?: string;
77
88
  [key: string]: unknown;
78
89
  }
90
+ /** Where a deployment came from. `verified` means the git fields were read from a GitHub OIDC token. */
91
+ export interface DeploySource {
92
+ kind: "api" | "cli" | "mcp" | "sdk" | "github-actions";
93
+ repository?: string;
94
+ ref?: string;
95
+ sha?: string;
96
+ /** First line of the commit message. */
97
+ message?: string;
98
+ actor?: string;
99
+ runUrl?: string;
100
+ verified?: boolean;
101
+ }
102
+ /** A project's link to a GitHub repository for push-to-deploy. */
103
+ export interface GitConnection {
104
+ provider: "github";
105
+ /** Lower-cased `owner/name`. */
106
+ repository: string;
107
+ /** The only branch that deploys. */
108
+ branch: string;
109
+ /** True once a workflow run from the repository has authenticated. */
110
+ verified: boolean;
111
+ connectedAt: string;
112
+ /** Audience the workflow must request its OIDC token for. */
113
+ audience: string;
114
+ /** Contents for `.github/workflows/novence.yml`. */
115
+ workflow: string;
116
+ }
117
+ /** Result of trading a GitHub Actions OIDC token for a short-lived deploy key. */
118
+ export interface GithubOidcExchange {
119
+ /** Deploy-only key for `projectId`. Expires at `expiresAt` (about 30 minutes). */
120
+ apiKey: string;
121
+ expiresAt: string;
122
+ projectId: string;
123
+ project: {
124
+ id: string;
125
+ name: string;
126
+ suffix: string;
127
+ url: string;
128
+ };
129
+ source: DeploySource;
130
+ }
131
+ export interface UploadDirResult {
132
+ /** Site paths uploaded from the directory. */
133
+ uploaded: string[];
134
+ /** Site paths deleted because the directory no longer has them. Empty with `prune: false`. */
135
+ removed: string[];
136
+ /** Site paths left alone although the directory lacks them (`/data/*.json`). */
137
+ kept: string[];
138
+ }
79
139
  export interface Deployment {
80
140
  id: string;
81
141
  status: DeploymentStatus;
142
+ source?: DeploySource | null;
143
+ /**
144
+ * True while a newer deploy is waiting for this one to settle. Keep polling
145
+ * `deployments.latest`: a deployment with a different id follows.
146
+ */
147
+ queuedRedeploy?: boolean;
82
148
  phase?: DeploymentPhase;
83
149
  /** 1-based place in the check-runner queue while `status` is `queued`; null otherwise. */
84
150
  queuePosition?: number | null;
@@ -181,6 +247,27 @@ export interface Quotas {
181
247
  /** Extra collaborators per project (owner excluded). Free/unverified is 0. */
182
248
  teamSeats: number;
183
249
  }
250
+ /** Monthly overage cap (Pro/Scale). Matches SpendLimitStatus in openapi.yaml. */
251
+ export interface SpendLimitStatus {
252
+ /** Cap in USD. null = no cap. */
253
+ limitUsd: number | null;
254
+ /** Month-to-date overage at list rates (excludes the base plan price). */
255
+ overageUsd: number;
256
+ remainingUsd: number | null;
257
+ /** overage / limit as a whole percent, capped at 100. null when the limit is null or 0. */
258
+ usedPct: number | null;
259
+ /** Only verified Pro/Scale accounts incur overage. A limit on Free is kept for later. */
260
+ applies: boolean;
261
+ reached: boolean;
262
+ /** What is paused right now. `bandwidth_gb` means live sites are paused. */
263
+ paused: Array<"bandwidth_gb" | "check_minutes" | "form_submissions" | "custom_domains">;
264
+ pausedLabels: string[];
265
+ sitesPaused: boolean;
266
+ period: {
267
+ start: string;
268
+ resetsAt: string;
269
+ };
270
+ }
184
271
  export interface ProjectUsage {
185
272
  /** Prefer storage_bytes over storage_gb for exact accounting. */
186
273
  storage_bytes: number;
@@ -258,6 +345,7 @@ export interface AccountSnapshot {
258
345
  emailVerified?: boolean;
259
346
  quotas?: Quotas;
260
347
  usage?: Record<string, number>;
348
+ spendLimit?: SpendLimitStatus;
261
349
  projects?: Array<Record<string, unknown>>;
262
350
  subscription?: {
263
351
  id: string;
@@ -390,14 +478,33 @@ export declare class Novence {
390
478
  uploadBuffer: (projectId: string, path: string, contentType: string | undefined, body: ArrayBuffer | Uint8Array) => Promise<{
391
479
  file: StagingFile;
392
480
  }>;
393
- /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
394
- uploadDir: (projectId: string, dir: string) => Promise<{
395
- uploaded: string[];
481
+ list: (projectId: string) => Promise<{
482
+ files: StagingFile[];
483
+ }>;
484
+ /** Remove one file from staging. It leaves the live site on the next deploy. */
485
+ delete: (projectId: string, path: string) => Promise<{
486
+ deleted: boolean;
396
487
  }>;
488
+ /**
489
+ * Node-only: make the project's files match `dir`. Uploads every allowed file with a
490
+ * root-relative site path, then removes files the directory no longer has, so a file
491
+ * deleted locally stops being served after the next deploy. `/data/*.json` is never
492
+ * removed (the live-data API writes it). Pass `{ prune: false }` to only add.
493
+ * Dot-files and dot-directories are skipped, except `.well-known/`.
494
+ */
495
+ uploadDir: (projectId: string, dir: string, opts?: {
496
+ prune?: boolean;
497
+ }) => Promise<UploadDirResult>;
397
498
  };
398
499
  deployments: {
500
+ /**
501
+ * Start a deploy. `source` records where it came from (shown by `deployments.latest`).
502
+ * Called while another deploy is in progress, it returns that deploy; if files changed
503
+ * since, `queuedRedeploy` is true and a follow-up starts once the first settles.
504
+ */
399
505
  create: (projectId: string, opts?: {
400
506
  force?: boolean;
507
+ source?: Partial<DeploySource>;
401
508
  }) => Promise<{
402
509
  deployment: Deployment;
403
510
  }>;
@@ -420,6 +527,29 @@ export declare class Novence {
420
527
  projectId?: string;
421
528
  force?: boolean;
422
529
  }): Promise<PublishHtmlResult>;
530
+ /** Optional push-to-deploy from a GitHub repository. Novence does not clone or build it. */
531
+ git: {
532
+ /** The project's repository connection, or null. */
533
+ get: (projectId: string) => Promise<{
534
+ connection: GitConnection | null;
535
+ }>;
536
+ /**
537
+ * Link the project to a repository (`owner/name` or a github.com URL). Only pushes to
538
+ * `branch` (default `main`) deploy. Write the returned `workflow` to
539
+ * `.github/workflows/novence.yml`; it authenticates with GitHub OIDC, so no API key
540
+ * is stored in the repository. Needs a verified email.
541
+ */
542
+ connect: (projectId: string, input: {
543
+ repository: string;
544
+ branch?: string;
545
+ }) => Promise<{
546
+ connection: GitConnection;
547
+ }>;
548
+ disconnect: (projectId: string) => Promise<{
549
+ disconnected: boolean;
550
+ repository: string | null;
551
+ }>;
552
+ };
423
553
  domains: {
424
554
  configure: (projectId: string, hostname: string, input?: {
425
555
  primary?: "www" | "apex";
@@ -487,7 +617,17 @@ export declare class Novence {
487
617
  quotas: Quotas;
488
618
  usage: Record<string, number>;
489
619
  bandwidthMetering?: string;
620
+ spendLimit?: SpendLimitStatus;
490
621
  }>;
622
+ /** Monthly overage cap, month-to-date overage, and what is paused. */
623
+ spendLimit: () => Promise<SpendLimitStatus>;
624
+ /**
625
+ * Set or change the monthly overage cap in USD (up to 2 decimals), or pass `null` to
626
+ * remove it. At the cap, anything that would add overage pauses — including live sites
627
+ * once bandwidth is past the included pool — until it is raised or the UTC month resets.
628
+ * `0` means never pay overage.
629
+ */
630
+ setSpendLimit: (limitUsd: number | null) => Promise<SpendLimitStatus>;
491
631
  checkout: (input: {
492
632
  successUrl?: string;
493
633
  cancelUrl?: string;
@@ -562,6 +702,17 @@ export declare class Novence {
562
702
  }>;
563
703
  };
564
704
  }
705
+ /**
706
+ * Inside a GitHub Actions job with `permissions: id-token: write`, trade the job's OIDC
707
+ * token for a short-lived, deploy-only key on the project its repository is connected to
708
+ * (`git.connect`). No stored secret. Throws a NovenceError whose `code` says why not:
709
+ * `repo_not_connected`, `branch_not_allowed`, `project_required`, `event_not_allowed`.
710
+ */
711
+ export declare function exchangeGithubOidc(opts?: {
712
+ baseUrl?: string;
713
+ projectId?: string;
714
+ env?: Record<string, string | undefined>;
715
+ }): Promise<GithubOidcExchange>;
565
716
  export interface SignupAttributionInput {
566
717
  method?: "web" | "mcp" | "cli" | "sdk" | "api";
567
718
  client?: string;
package/dist/cjs/index.js CHANGED
@@ -2,6 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.Novence = exports.CONSOLE_INJECT_MARKER = exports.NovenceError = exports.DEFAULT_BASE_URL = void 0;
4
4
  exports.isNovenceClient = isNovenceClient;
5
+ exports.exchangeGithubOidc = exchangeGithubOidc;
5
6
  exports.bootstrapAccount = bootstrapAccount;
6
7
  exports.createDemoAccount = createDemoAccount;
7
8
  exports.claimAccount = claimAccount;
@@ -45,10 +46,21 @@ function isNovenceClient(value) {
45
46
  */
46
47
  class NovenceError extends Error {
47
48
  status;
48
- constructor(message, status) {
49
+ /**
50
+ * On a 402, which wall was hit: `verify` (email OTP), `upgrade` (Checkout/MPP), or
51
+ * `spend_limit` (the account's own overage cap — raise it with billing.setSpendLimit).
52
+ */
53
+ wall;
54
+ /** Machine-readable reason when the API sends one, e.g. `repo_not_connected`. */
55
+ code;
56
+ constructor(message, status, wall, code) {
49
57
  super(message);
50
58
  this.name = "NovenceError";
51
59
  this.status = status;
60
+ if (wall)
61
+ this.wall = wall;
62
+ if (code)
63
+ this.code = code;
52
64
  }
53
65
  }
54
66
  exports.NovenceError = NovenceError;
@@ -102,7 +114,8 @@ class Novence {
102
114
  });
103
115
  const data = (await res.json());
104
116
  if (!res.ok) {
105
- throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
117
+ const err = data;
118
+ throw new NovenceError(err.error ?? `HTTP ${res.status}`, res.status, typeof err.wall === "string" ? err.wall : undefined, typeof err.code === "string" ? err.code : undefined);
106
119
  }
107
120
  return data;
108
121
  }
@@ -164,12 +177,21 @@ class Novence {
164
177
  throw new NovenceError(`Upload failed for ${path}`, put.status);
165
178
  return this.files.confirm(projectId, path, type);
166
179
  },
167
- /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
168
- uploadDir: async (projectId, dir) => {
180
+ list: (projectId) => this.request("GET", `/v1/projects/${projectId}/files`),
181
+ /** Remove one file from staging. It leaves the live site on the next deploy. */
182
+ delete: (projectId, path) => this.request("DELETE", `/v1/projects/${projectId}/files/${encodeSitePath(path)}`),
183
+ /**
184
+ * Node-only: make the project's files match `dir`. Uploads every allowed file with a
185
+ * root-relative site path, then removes files the directory no longer has, so a file
186
+ * deleted locally stops being served after the next deploy. `/data/*.json` is never
187
+ * removed (the live-data API writes it). Pass `{ prune: false }` to only add.
188
+ * Dot-files and dot-directories are skipped, except `.well-known/`.
189
+ */
190
+ uploadDir: async (projectId, dir, opts = {}) => {
169
191
  function walk(current) {
170
192
  const out = [];
171
193
  for (const name of (0, node_fs_1.readdirSync)(current)) {
172
- if (name.startsWith("."))
194
+ if (name.startsWith(".") && name !== ".well-known")
173
195
  continue;
174
196
  const full = (0, node_path_1.join)(current, name);
175
197
  if ((0, node_fs_1.statSync)(full).isDirectory())
@@ -191,10 +213,32 @@ class Novence {
191
213
  await this.files.uploadBuffer(projectId, rel, contentType, body);
192
214
  uploaded.push(rel);
193
215
  }
194
- return { uploaded };
216
+ const removed = [];
217
+ const kept = [];
218
+ // Never prune from an empty walk: a wrong directory must not wipe the site.
219
+ if (opts.prune !== false && uploaded.length > 0) {
220
+ const present = new Set(uploaded);
221
+ const { files } = await this.files.list(projectId);
222
+ for (const file of files) {
223
+ if (present.has(file.path))
224
+ continue;
225
+ if (isPruneProtectedPath(file.path)) {
226
+ kept.push(file.path);
227
+ continue;
228
+ }
229
+ await this.files.delete(projectId, file.path);
230
+ removed.push(file.path);
231
+ }
232
+ }
233
+ return { uploaded, removed, kept };
195
234
  },
196
235
  };
197
236
  deployments = {
237
+ /**
238
+ * Start a deploy. `source` records where it came from (shown by `deployments.latest`).
239
+ * Called while another deploy is in progress, it returns that deploy; if files changed
240
+ * since, `queuedRedeploy` is true and a follow-up starts once the first settles.
241
+ */
198
242
  create: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/deployments`, opts ?? {}),
199
243
  latest: (projectId) => this.request("GET", `/v1/projects/${projectId}/deployments/latest`),
200
244
  rollback: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/rollback`, opts ?? {}),
@@ -213,6 +257,19 @@ class Novence {
213
257
  force: input.force,
214
258
  });
215
259
  }
260
+ /** Optional push-to-deploy from a GitHub repository. Novence does not clone or build it. */
261
+ git = {
262
+ /** The project's repository connection, or null. */
263
+ get: (projectId) => this.request("GET", `/v1/projects/${projectId}/git`),
264
+ /**
265
+ * Link the project to a repository (`owner/name` or a github.com URL). Only pushes to
266
+ * `branch` (default `main`) deploy. Write the returned `workflow` to
267
+ * `.github/workflows/novence.yml`; it authenticates with GitHub OIDC, so no API key
268
+ * is stored in the repository. Needs a verified email.
269
+ */
270
+ connect: (projectId, input) => this.request("PUT", `/v1/projects/${projectId}/git`, input),
271
+ disconnect: (projectId) => this.request("DELETE", `/v1/projects/${projectId}/git`),
272
+ };
216
273
  domains = {
217
274
  configure: (projectId, hostname, input) => this.request("POST", `/v1/projects/${projectId}/domains`, {
218
275
  hostname,
@@ -243,6 +300,15 @@ class Novence {
243
300
  };
244
301
  billing = {
245
302
  quotas: () => this.request("GET", "/v1/billing/quotas"),
303
+ /** Monthly overage cap, month-to-date overage, and what is paused. */
304
+ spendLimit: () => this.request("GET", "/v1/billing/spend-limit"),
305
+ /**
306
+ * Set or change the monthly overage cap in USD (up to 2 decimals), or pass `null` to
307
+ * remove it. At the cap, anything that would add overage pauses — including live sites
308
+ * once bandwidth is past the included pool — until it is raised or the UTC month resets.
309
+ * `0` means never pay overage.
310
+ */
311
+ setSpendLimit: (limitUsd) => this.request("PUT", "/v1/billing/spend-limit", { limitUsd }),
246
312
  checkout: (input) => this.request("POST", "/v1/billing/checkout", input),
247
313
  portal: (input = {}) => this.request("POST", "/v1/billing/portal", input),
248
314
  /**
@@ -305,6 +371,50 @@ class Novence {
305
371
  };
306
372
  }
307
373
  exports.Novence = Novence;
374
+ /** Percent-encode a site path for a `/files/*` URL, keeping the slashes. */
375
+ function encodeSitePath(path) {
376
+ return path.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
377
+ }
378
+ /** Paths `uploadDir` never prunes: `/data/*.json` belongs to the live-data API. */
379
+ function isPruneProtectedPath(path) {
380
+ return /^\/data\/[^/]+\.json$/i.test(path);
381
+ }
382
+ /**
383
+ * Inside a GitHub Actions job with `permissions: id-token: write`, trade the job's OIDC
384
+ * token for a short-lived, deploy-only key on the project its repository is connected to
385
+ * (`git.connect`). No stored secret. Throws a NovenceError whose `code` says why not:
386
+ * `repo_not_connected`, `branch_not_allowed`, `project_required`, `event_not_allowed`.
387
+ */
388
+ async function exchangeGithubOidc(opts = {}) {
389
+ const env = opts.env ?? process.env;
390
+ const requestUrl = env.ACTIONS_ID_TOKEN_REQUEST_URL;
391
+ const requestToken = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
392
+ if (!requestUrl || !requestToken) {
393
+ throw new NovenceError("No GitHub OIDC token available. Add `permissions: id-token: write` to the workflow job.", 400, undefined, "oidc_unavailable");
394
+ }
395
+ const base = resolveBaseUrl(opts.baseUrl);
396
+ // The API only accepts tokens minted for it; the audience is its own origin.
397
+ const audience = new URL(base).origin;
398
+ const tokenUrl = new URL(requestUrl);
399
+ tokenUrl.searchParams.set("audience", audience);
400
+ const tokenRes = await fetch(tokenUrl, {
401
+ headers: { Authorization: `Bearer ${requestToken}`, Accept: "application/json" },
402
+ });
403
+ const tokenBody = (await tokenRes.json().catch(() => ({})));
404
+ if (!tokenRes.ok || !tokenBody.value) {
405
+ throw new NovenceError(`GitHub did not issue an OIDC token (HTTP ${tokenRes.status}).`, tokenRes.status || 500, undefined, "oidc_unavailable");
406
+ }
407
+ const res = await fetch(`${base}/v1/auth/github-oidc`, {
408
+ method: "POST",
409
+ headers: { "Content-Type": "application/json" },
410
+ body: JSON.stringify({ token: tokenBody.value, projectId: opts.projectId }),
411
+ });
412
+ const data = (await readErrorBody(res));
413
+ if (!res.ok) {
414
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status, undefined, data.code);
415
+ }
416
+ return data;
417
+ }
308
418
  function withMethod(attribution, method) {
309
419
  return { ...attribution, method: attribution?.method ?? method };
310
420
  }
@@ -8,7 +8,14 @@ export declare function isNovenceClient(value: unknown): value is Novence;
8
8
  */
9
9
  export declare class NovenceError extends Error {
10
10
  readonly status: number;
11
- constructor(message: string, status: number);
11
+ /**
12
+ * On a 402, which wall was hit: `verify` (email OTP), `upgrade` (Checkout/MPP), or
13
+ * `spend_limit` (the account's own overage cap — raise it with billing.setSpendLimit).
14
+ */
15
+ readonly wall?: string;
16
+ /** Machine-readable reason when the API sends one, e.g. `repo_not_connected`. */
17
+ readonly code?: string;
18
+ constructor(message: string, status: number, wall?: string, code?: string);
12
19
  }
13
20
  export interface NovenceOptions {
14
21
  apiKey: string;
@@ -74,11 +81,70 @@ export interface ChecksResults {
74
81
  reason?: string;
75
82
  /** Non-blocking findings, e.g. low Lighthouse performance while `enforcePerformance` is off. */
76
83
  warnings?: string[];
84
+ /** The deployment these results were measured from. */
85
+ deploymentId?: string;
86
+ /** Why the page could not be scored. The deploy fails and `lighthouse` is null. */
87
+ measurementError?: string;
77
88
  [key: string]: unknown;
78
89
  }
90
+ /** Where a deployment came from. `verified` means the git fields were read from a GitHub OIDC token. */
91
+ export interface DeploySource {
92
+ kind: "api" | "cli" | "mcp" | "sdk" | "github-actions";
93
+ repository?: string;
94
+ ref?: string;
95
+ sha?: string;
96
+ /** First line of the commit message. */
97
+ message?: string;
98
+ actor?: string;
99
+ runUrl?: string;
100
+ verified?: boolean;
101
+ }
102
+ /** A project's link to a GitHub repository for push-to-deploy. */
103
+ export interface GitConnection {
104
+ provider: "github";
105
+ /** Lower-cased `owner/name`. */
106
+ repository: string;
107
+ /** The only branch that deploys. */
108
+ branch: string;
109
+ /** True once a workflow run from the repository has authenticated. */
110
+ verified: boolean;
111
+ connectedAt: string;
112
+ /** Audience the workflow must request its OIDC token for. */
113
+ audience: string;
114
+ /** Contents for `.github/workflows/novence.yml`. */
115
+ workflow: string;
116
+ }
117
+ /** Result of trading a GitHub Actions OIDC token for a short-lived deploy key. */
118
+ export interface GithubOidcExchange {
119
+ /** Deploy-only key for `projectId`. Expires at `expiresAt` (about 30 minutes). */
120
+ apiKey: string;
121
+ expiresAt: string;
122
+ projectId: string;
123
+ project: {
124
+ id: string;
125
+ name: string;
126
+ suffix: string;
127
+ url: string;
128
+ };
129
+ source: DeploySource;
130
+ }
131
+ export interface UploadDirResult {
132
+ /** Site paths uploaded from the directory. */
133
+ uploaded: string[];
134
+ /** Site paths deleted because the directory no longer has them. Empty with `prune: false`. */
135
+ removed: string[];
136
+ /** Site paths left alone although the directory lacks them (`/data/*.json`). */
137
+ kept: string[];
138
+ }
79
139
  export interface Deployment {
80
140
  id: string;
81
141
  status: DeploymentStatus;
142
+ source?: DeploySource | null;
143
+ /**
144
+ * True while a newer deploy is waiting for this one to settle. Keep polling
145
+ * `deployments.latest`: a deployment with a different id follows.
146
+ */
147
+ queuedRedeploy?: boolean;
82
148
  phase?: DeploymentPhase;
83
149
  /** 1-based place in the check-runner queue while `status` is `queued`; null otherwise. */
84
150
  queuePosition?: number | null;
@@ -181,6 +247,27 @@ export interface Quotas {
181
247
  /** Extra collaborators per project (owner excluded). Free/unverified is 0. */
182
248
  teamSeats: number;
183
249
  }
250
+ /** Monthly overage cap (Pro/Scale). Matches SpendLimitStatus in openapi.yaml. */
251
+ export interface SpendLimitStatus {
252
+ /** Cap in USD. null = no cap. */
253
+ limitUsd: number | null;
254
+ /** Month-to-date overage at list rates (excludes the base plan price). */
255
+ overageUsd: number;
256
+ remainingUsd: number | null;
257
+ /** overage / limit as a whole percent, capped at 100. null when the limit is null or 0. */
258
+ usedPct: number | null;
259
+ /** Only verified Pro/Scale accounts incur overage. A limit on Free is kept for later. */
260
+ applies: boolean;
261
+ reached: boolean;
262
+ /** What is paused right now. `bandwidth_gb` means live sites are paused. */
263
+ paused: Array<"bandwidth_gb" | "check_minutes" | "form_submissions" | "custom_domains">;
264
+ pausedLabels: string[];
265
+ sitesPaused: boolean;
266
+ period: {
267
+ start: string;
268
+ resetsAt: string;
269
+ };
270
+ }
184
271
  export interface ProjectUsage {
185
272
  /** Prefer storage_bytes over storage_gb for exact accounting. */
186
273
  storage_bytes: number;
@@ -258,6 +345,7 @@ export interface AccountSnapshot {
258
345
  emailVerified?: boolean;
259
346
  quotas?: Quotas;
260
347
  usage?: Record<string, number>;
348
+ spendLimit?: SpendLimitStatus;
261
349
  projects?: Array<Record<string, unknown>>;
262
350
  subscription?: {
263
351
  id: string;
@@ -390,14 +478,33 @@ export declare class Novence {
390
478
  uploadBuffer: (projectId: string, path: string, contentType: string | undefined, body: ArrayBuffer | Uint8Array) => Promise<{
391
479
  file: StagingFile;
392
480
  }>;
393
- /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
394
- uploadDir: (projectId: string, dir: string) => Promise<{
395
- uploaded: string[];
481
+ list: (projectId: string) => Promise<{
482
+ files: StagingFile[];
483
+ }>;
484
+ /** Remove one file from staging. It leaves the live site on the next deploy. */
485
+ delete: (projectId: string, path: string) => Promise<{
486
+ deleted: boolean;
396
487
  }>;
488
+ /**
489
+ * Node-only: make the project's files match `dir`. Uploads every allowed file with a
490
+ * root-relative site path, then removes files the directory no longer has, so a file
491
+ * deleted locally stops being served after the next deploy. `/data/*.json` is never
492
+ * removed (the live-data API writes it). Pass `{ prune: false }` to only add.
493
+ * Dot-files and dot-directories are skipped, except `.well-known/`.
494
+ */
495
+ uploadDir: (projectId: string, dir: string, opts?: {
496
+ prune?: boolean;
497
+ }) => Promise<UploadDirResult>;
397
498
  };
398
499
  deployments: {
500
+ /**
501
+ * Start a deploy. `source` records where it came from (shown by `deployments.latest`).
502
+ * Called while another deploy is in progress, it returns that deploy; if files changed
503
+ * since, `queuedRedeploy` is true and a follow-up starts once the first settles.
504
+ */
399
505
  create: (projectId: string, opts?: {
400
506
  force?: boolean;
507
+ source?: Partial<DeploySource>;
401
508
  }) => Promise<{
402
509
  deployment: Deployment;
403
510
  }>;
@@ -420,6 +527,29 @@ export declare class Novence {
420
527
  projectId?: string;
421
528
  force?: boolean;
422
529
  }): Promise<PublishHtmlResult>;
530
+ /** Optional push-to-deploy from a GitHub repository. Novence does not clone or build it. */
531
+ git: {
532
+ /** The project's repository connection, or null. */
533
+ get: (projectId: string) => Promise<{
534
+ connection: GitConnection | null;
535
+ }>;
536
+ /**
537
+ * Link the project to a repository (`owner/name` or a github.com URL). Only pushes to
538
+ * `branch` (default `main`) deploy. Write the returned `workflow` to
539
+ * `.github/workflows/novence.yml`; it authenticates with GitHub OIDC, so no API key
540
+ * is stored in the repository. Needs a verified email.
541
+ */
542
+ connect: (projectId: string, input: {
543
+ repository: string;
544
+ branch?: string;
545
+ }) => Promise<{
546
+ connection: GitConnection;
547
+ }>;
548
+ disconnect: (projectId: string) => Promise<{
549
+ disconnected: boolean;
550
+ repository: string | null;
551
+ }>;
552
+ };
423
553
  domains: {
424
554
  configure: (projectId: string, hostname: string, input?: {
425
555
  primary?: "www" | "apex";
@@ -487,7 +617,17 @@ export declare class Novence {
487
617
  quotas: Quotas;
488
618
  usage: Record<string, number>;
489
619
  bandwidthMetering?: string;
620
+ spendLimit?: SpendLimitStatus;
490
621
  }>;
622
+ /** Monthly overage cap, month-to-date overage, and what is paused. */
623
+ spendLimit: () => Promise<SpendLimitStatus>;
624
+ /**
625
+ * Set or change the monthly overage cap in USD (up to 2 decimals), or pass `null` to
626
+ * remove it. At the cap, anything that would add overage pauses — including live sites
627
+ * once bandwidth is past the included pool — until it is raised or the UTC month resets.
628
+ * `0` means never pay overage.
629
+ */
630
+ setSpendLimit: (limitUsd: number | null) => Promise<SpendLimitStatus>;
491
631
  checkout: (input: {
492
632
  successUrl?: string;
493
633
  cancelUrl?: string;
@@ -562,6 +702,17 @@ export declare class Novence {
562
702
  }>;
563
703
  };
564
704
  }
705
+ /**
706
+ * Inside a GitHub Actions job with `permissions: id-token: write`, trade the job's OIDC
707
+ * token for a short-lived, deploy-only key on the project its repository is connected to
708
+ * (`git.connect`). No stored secret. Throws a NovenceError whose `code` says why not:
709
+ * `repo_not_connected`, `branch_not_allowed`, `project_required`, `event_not_allowed`.
710
+ */
711
+ export declare function exchangeGithubOidc(opts?: {
712
+ baseUrl?: string;
713
+ projectId?: string;
714
+ env?: Record<string, string | undefined>;
715
+ }): Promise<GithubOidcExchange>;
565
716
  export interface SignupAttributionInput {
566
717
  method?: "web" | "mcp" | "cli" | "sdk" | "api";
567
718
  client?: string;
package/dist/esm/index.js CHANGED
@@ -33,10 +33,21 @@ export function isNovenceClient(value) {
33
33
  */
34
34
  export class NovenceError extends Error {
35
35
  status;
36
- constructor(message, status) {
36
+ /**
37
+ * On a 402, which wall was hit: `verify` (email OTP), `upgrade` (Checkout/MPP), or
38
+ * `spend_limit` (the account's own overage cap — raise it with billing.setSpendLimit).
39
+ */
40
+ wall;
41
+ /** Machine-readable reason when the API sends one, e.g. `repo_not_connected`. */
42
+ code;
43
+ constructor(message, status, wall, code) {
37
44
  super(message);
38
45
  this.name = "NovenceError";
39
46
  this.status = status;
47
+ if (wall)
48
+ this.wall = wall;
49
+ if (code)
50
+ this.code = code;
40
51
  }
41
52
  }
42
53
  /** Marker in `ConsoleKit.htmlTemplate` to replace with the snapshot + token globals. */
@@ -89,7 +100,8 @@ export class Novence {
89
100
  });
90
101
  const data = (await res.json());
91
102
  if (!res.ok) {
92
- throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
103
+ const err = data;
104
+ throw new NovenceError(err.error ?? `HTTP ${res.status}`, res.status, typeof err.wall === "string" ? err.wall : undefined, typeof err.code === "string" ? err.code : undefined);
93
105
  }
94
106
  return data;
95
107
  }
@@ -151,12 +163,21 @@ export class Novence {
151
163
  throw new NovenceError(`Upload failed for ${path}`, put.status);
152
164
  return this.files.confirm(projectId, path, type);
153
165
  },
154
- /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
155
- uploadDir: async (projectId, dir) => {
166
+ list: (projectId) => this.request("GET", `/v1/projects/${projectId}/files`),
167
+ /** Remove one file from staging. It leaves the live site on the next deploy. */
168
+ delete: (projectId, path) => this.request("DELETE", `/v1/projects/${projectId}/files/${encodeSitePath(path)}`),
169
+ /**
170
+ * Node-only: make the project's files match `dir`. Uploads every allowed file with a
171
+ * root-relative site path, then removes files the directory no longer has, so a file
172
+ * deleted locally stops being served after the next deploy. `/data/*.json` is never
173
+ * removed (the live-data API writes it). Pass `{ prune: false }` to only add.
174
+ * Dot-files and dot-directories are skipped, except `.well-known/`.
175
+ */
176
+ uploadDir: async (projectId, dir, opts = {}) => {
156
177
  function walk(current) {
157
178
  const out = [];
158
179
  for (const name of readdirSync(current)) {
159
- if (name.startsWith("."))
180
+ if (name.startsWith(".") && name !== ".well-known")
160
181
  continue;
161
182
  const full = join(current, name);
162
183
  if (statSync(full).isDirectory())
@@ -178,10 +199,32 @@ export class Novence {
178
199
  await this.files.uploadBuffer(projectId, rel, contentType, body);
179
200
  uploaded.push(rel);
180
201
  }
181
- return { uploaded };
202
+ const removed = [];
203
+ const kept = [];
204
+ // Never prune from an empty walk: a wrong directory must not wipe the site.
205
+ if (opts.prune !== false && uploaded.length > 0) {
206
+ const present = new Set(uploaded);
207
+ const { files } = await this.files.list(projectId);
208
+ for (const file of files) {
209
+ if (present.has(file.path))
210
+ continue;
211
+ if (isPruneProtectedPath(file.path)) {
212
+ kept.push(file.path);
213
+ continue;
214
+ }
215
+ await this.files.delete(projectId, file.path);
216
+ removed.push(file.path);
217
+ }
218
+ }
219
+ return { uploaded, removed, kept };
182
220
  },
183
221
  };
184
222
  deployments = {
223
+ /**
224
+ * Start a deploy. `source` records where it came from (shown by `deployments.latest`).
225
+ * Called while another deploy is in progress, it returns that deploy; if files changed
226
+ * since, `queuedRedeploy` is true and a follow-up starts once the first settles.
227
+ */
185
228
  create: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/deployments`, opts ?? {}),
186
229
  latest: (projectId) => this.request("GET", `/v1/projects/${projectId}/deployments/latest`),
187
230
  rollback: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/rollback`, opts ?? {}),
@@ -200,6 +243,19 @@ export class Novence {
200
243
  force: input.force,
201
244
  });
202
245
  }
246
+ /** Optional push-to-deploy from a GitHub repository. Novence does not clone or build it. */
247
+ git = {
248
+ /** The project's repository connection, or null. */
249
+ get: (projectId) => this.request("GET", `/v1/projects/${projectId}/git`),
250
+ /**
251
+ * Link the project to a repository (`owner/name` or a github.com URL). Only pushes to
252
+ * `branch` (default `main`) deploy. Write the returned `workflow` to
253
+ * `.github/workflows/novence.yml`; it authenticates with GitHub OIDC, so no API key
254
+ * is stored in the repository. Needs a verified email.
255
+ */
256
+ connect: (projectId, input) => this.request("PUT", `/v1/projects/${projectId}/git`, input),
257
+ disconnect: (projectId) => this.request("DELETE", `/v1/projects/${projectId}/git`),
258
+ };
203
259
  domains = {
204
260
  configure: (projectId, hostname, input) => this.request("POST", `/v1/projects/${projectId}/domains`, {
205
261
  hostname,
@@ -230,6 +286,15 @@ export class Novence {
230
286
  };
231
287
  billing = {
232
288
  quotas: () => this.request("GET", "/v1/billing/quotas"),
289
+ /** Monthly overage cap, month-to-date overage, and what is paused. */
290
+ spendLimit: () => this.request("GET", "/v1/billing/spend-limit"),
291
+ /**
292
+ * Set or change the monthly overage cap in USD (up to 2 decimals), or pass `null` to
293
+ * remove it. At the cap, anything that would add overage pauses — including live sites
294
+ * once bandwidth is past the included pool — until it is raised or the UTC month resets.
295
+ * `0` means never pay overage.
296
+ */
297
+ setSpendLimit: (limitUsd) => this.request("PUT", "/v1/billing/spend-limit", { limitUsd }),
233
298
  checkout: (input) => this.request("POST", "/v1/billing/checkout", input),
234
299
  portal: (input = {}) => this.request("POST", "/v1/billing/portal", input),
235
300
  /**
@@ -291,6 +356,50 @@ export class Novence {
291
356
  revoke: (id, opts = {}) => this.request("DELETE", `/v1/api-keys/${id}${opts.force ? "?force=true" : ""}`),
292
357
  };
293
358
  }
359
+ /** Percent-encode a site path for a `/files/*` URL, keeping the slashes. */
360
+ function encodeSitePath(path) {
361
+ return path.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
362
+ }
363
+ /** Paths `uploadDir` never prunes: `/data/*.json` belongs to the live-data API. */
364
+ function isPruneProtectedPath(path) {
365
+ return /^\/data\/[^/]+\.json$/i.test(path);
366
+ }
367
+ /**
368
+ * Inside a GitHub Actions job with `permissions: id-token: write`, trade the job's OIDC
369
+ * token for a short-lived, deploy-only key on the project its repository is connected to
370
+ * (`git.connect`). No stored secret. Throws a NovenceError whose `code` says why not:
371
+ * `repo_not_connected`, `branch_not_allowed`, `project_required`, `event_not_allowed`.
372
+ */
373
+ export async function exchangeGithubOidc(opts = {}) {
374
+ const env = opts.env ?? process.env;
375
+ const requestUrl = env.ACTIONS_ID_TOKEN_REQUEST_URL;
376
+ const requestToken = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
377
+ if (!requestUrl || !requestToken) {
378
+ throw new NovenceError("No GitHub OIDC token available. Add `permissions: id-token: write` to the workflow job.", 400, undefined, "oidc_unavailable");
379
+ }
380
+ const base = resolveBaseUrl(opts.baseUrl);
381
+ // The API only accepts tokens minted for it; the audience is its own origin.
382
+ const audience = new URL(base).origin;
383
+ const tokenUrl = new URL(requestUrl);
384
+ tokenUrl.searchParams.set("audience", audience);
385
+ const tokenRes = await fetch(tokenUrl, {
386
+ headers: { Authorization: `Bearer ${requestToken}`, Accept: "application/json" },
387
+ });
388
+ const tokenBody = (await tokenRes.json().catch(() => ({})));
389
+ if (!tokenRes.ok || !tokenBody.value) {
390
+ throw new NovenceError(`GitHub did not issue an OIDC token (HTTP ${tokenRes.status}).`, tokenRes.status || 500, undefined, "oidc_unavailable");
391
+ }
392
+ const res = await fetch(`${base}/v1/auth/github-oidc`, {
393
+ method: "POST",
394
+ headers: { "Content-Type": "application/json" },
395
+ body: JSON.stringify({ token: tokenBody.value, projectId: opts.projectId }),
396
+ });
397
+ const data = (await readErrorBody(res));
398
+ if (!res.ok) {
399
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status, undefined, data.code);
400
+ }
401
+ return data;
402
+ }
294
403
  function withMethod(attribution, method) {
295
404
  return { ...attribution, method: attribution?.method ?? method };
296
405
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@novence/sdk",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
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",