@novence/sdk 0.3.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 +47 -3
- package/dist/cjs/index.d.ts +187 -4
- package/dist/cjs/index.js +122 -6
- package/dist/esm/index.d.ts +187 -4
- package/dist/esm/index.js +121 -6
- package/package.json +1 -1
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`:
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -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
|
-
|
|
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;
|
|
@@ -40,6 +47,30 @@ export interface Project {
|
|
|
40
47
|
createdAt?: string;
|
|
41
48
|
updatedAt?: string;
|
|
42
49
|
}
|
|
50
|
+
/** Result of `projects.delete`. Calling it on an already-deleted project returns `alreadyDeleted: true`. */
|
|
51
|
+
export interface ProjectDeleteResult {
|
|
52
|
+
deleted: true;
|
|
53
|
+
alreadyDeleted: boolean;
|
|
54
|
+
project: {
|
|
55
|
+
id: string;
|
|
56
|
+
name: string;
|
|
57
|
+
suffix: string;
|
|
58
|
+
url: string;
|
|
59
|
+
customDomain: string | null;
|
|
60
|
+
};
|
|
61
|
+
deletedAt: string;
|
|
62
|
+
/** Custom-domain hosts unmapped at the edge by this call. */
|
|
63
|
+
customDomainHostsReleased: string[];
|
|
64
|
+
/** Site files are erased after the response unless the purge already finished. */
|
|
65
|
+
storage: {
|
|
66
|
+
status: "purged";
|
|
67
|
+
objectsDeleted: number;
|
|
68
|
+
} | {
|
|
69
|
+
status: "purging";
|
|
70
|
+
};
|
|
71
|
+
/** Edge cleanup steps that failed. Call `projects.delete` again to retry them. */
|
|
72
|
+
warnings: string[];
|
|
73
|
+
}
|
|
43
74
|
/**
|
|
44
75
|
* Quality-gate payload. When `skipped` is true (unverified accounts), `passed`
|
|
45
76
|
* is null — do not treat that as checks having passed.
|
|
@@ -50,11 +81,70 @@ export interface ChecksResults {
|
|
|
50
81
|
reason?: string;
|
|
51
82
|
/** Non-blocking findings, e.g. low Lighthouse performance while `enforcePerformance` is off. */
|
|
52
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;
|
|
53
88
|
[key: string]: unknown;
|
|
54
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
|
+
}
|
|
55
139
|
export interface Deployment {
|
|
56
140
|
id: string;
|
|
57
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;
|
|
58
148
|
phase?: DeploymentPhase;
|
|
59
149
|
/** 1-based place in the check-runner queue while `status` is `queued`; null otherwise. */
|
|
60
150
|
queuePosition?: number | null;
|
|
@@ -157,6 +247,27 @@ export interface Quotas {
|
|
|
157
247
|
/** Extra collaborators per project (owner excluded). Free/unverified is 0. */
|
|
158
248
|
teamSeats: number;
|
|
159
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
|
+
}
|
|
160
271
|
export interface ProjectUsage {
|
|
161
272
|
/** Prefer storage_bytes over storage_gb for exact accounting. */
|
|
162
273
|
storage_bytes: number;
|
|
@@ -234,6 +345,7 @@ export interface AccountSnapshot {
|
|
|
234
345
|
emailVerified?: boolean;
|
|
235
346
|
quotas?: Quotas;
|
|
236
347
|
usage?: Record<string, number>;
|
|
348
|
+
spendLimit?: SpendLimitStatus;
|
|
237
349
|
projects?: Array<Record<string, unknown>>;
|
|
238
350
|
subscription?: {
|
|
239
351
|
id: string;
|
|
@@ -302,6 +414,14 @@ export declare class Novence {
|
|
|
302
414
|
}) => Promise<{
|
|
303
415
|
project: Project;
|
|
304
416
|
}>;
|
|
417
|
+
/**
|
|
418
|
+
* Permanently delete a project (owner only, account key). Irreversible: the site goes
|
|
419
|
+
* offline on every host and its files are erased. `confirm` must equal the project's
|
|
420
|
+
* exact name or suffix.
|
|
421
|
+
*/
|
|
422
|
+
delete: (id: string, input: {
|
|
423
|
+
confirm: string;
|
|
424
|
+
}) => Promise<ProjectDeleteResult>;
|
|
305
425
|
usage: (id: string) => Promise<{
|
|
306
426
|
projectId: string;
|
|
307
427
|
period: {
|
|
@@ -358,14 +478,33 @@ export declare class Novence {
|
|
|
358
478
|
uploadBuffer: (projectId: string, path: string, contentType: string | undefined, body: ArrayBuffer | Uint8Array) => Promise<{
|
|
359
479
|
file: StagingFile;
|
|
360
480
|
}>;
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
uploaded: string[];
|
|
481
|
+
list: (projectId: string) => Promise<{
|
|
482
|
+
files: StagingFile[];
|
|
364
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;
|
|
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>;
|
|
365
498
|
};
|
|
366
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
|
+
*/
|
|
367
505
|
create: (projectId: string, opts?: {
|
|
368
506
|
force?: boolean;
|
|
507
|
+
source?: Partial<DeploySource>;
|
|
369
508
|
}) => Promise<{
|
|
370
509
|
deployment: Deployment;
|
|
371
510
|
}>;
|
|
@@ -388,6 +527,29 @@ export declare class Novence {
|
|
|
388
527
|
projectId?: string;
|
|
389
528
|
force?: boolean;
|
|
390
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
|
+
};
|
|
391
553
|
domains: {
|
|
392
554
|
configure: (projectId: string, hostname: string, input?: {
|
|
393
555
|
primary?: "www" | "apex";
|
|
@@ -455,7 +617,17 @@ export declare class Novence {
|
|
|
455
617
|
quotas: Quotas;
|
|
456
618
|
usage: Record<string, number>;
|
|
457
619
|
bandwidthMetering?: string;
|
|
620
|
+
spendLimit?: SpendLimitStatus;
|
|
458
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>;
|
|
459
631
|
checkout: (input: {
|
|
460
632
|
successUrl?: string;
|
|
461
633
|
cancelUrl?: string;
|
|
@@ -530,6 +702,17 @@ export declare class Novence {
|
|
|
530
702
|
}>;
|
|
531
703
|
};
|
|
532
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>;
|
|
533
716
|
export interface SignupAttributionInput {
|
|
534
717
|
method?: "web" | "mcp" | "cli" | "sdk" | "api";
|
|
535
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
|
-
|
|
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
|
-
|
|
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
|
}
|
|
@@ -111,6 +124,12 @@ class Novence {
|
|
|
111
124
|
list: () => this.request("GET", "/v1/projects"),
|
|
112
125
|
get: (id) => this.request("GET", `/v1/projects/${id}`),
|
|
113
126
|
update: (id, input) => this.request("PATCH", `/v1/projects/${id}`, input),
|
|
127
|
+
/**
|
|
128
|
+
* Permanently delete a project (owner only, account key). Irreversible: the site goes
|
|
129
|
+
* offline on every host and its files are erased. `confirm` must equal the project's
|
|
130
|
+
* exact name or suffix.
|
|
131
|
+
*/
|
|
132
|
+
delete: (id, input) => this.request("DELETE", `/v1/projects/${id}`, { confirm: input.confirm }),
|
|
114
133
|
usage: (id) => this.request("GET", `/v1/projects/${id}/usage`),
|
|
115
134
|
analytics: (id, range) => {
|
|
116
135
|
const q = new URLSearchParams();
|
|
@@ -158,12 +177,21 @@ class Novence {
|
|
|
158
177
|
throw new NovenceError(`Upload failed for ${path}`, put.status);
|
|
159
178
|
return this.files.confirm(projectId, path, type);
|
|
160
179
|
},
|
|
161
|
-
|
|
162
|
-
|
|
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 = {}) => {
|
|
163
191
|
function walk(current) {
|
|
164
192
|
const out = [];
|
|
165
193
|
for (const name of (0, node_fs_1.readdirSync)(current)) {
|
|
166
|
-
if (name.startsWith("."))
|
|
194
|
+
if (name.startsWith(".") && name !== ".well-known")
|
|
167
195
|
continue;
|
|
168
196
|
const full = (0, node_path_1.join)(current, name);
|
|
169
197
|
if ((0, node_fs_1.statSync)(full).isDirectory())
|
|
@@ -185,10 +213,32 @@ class Novence {
|
|
|
185
213
|
await this.files.uploadBuffer(projectId, rel, contentType, body);
|
|
186
214
|
uploaded.push(rel);
|
|
187
215
|
}
|
|
188
|
-
|
|
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 };
|
|
189
234
|
},
|
|
190
235
|
};
|
|
191
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
|
+
*/
|
|
192
242
|
create: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/deployments`, opts ?? {}),
|
|
193
243
|
latest: (projectId) => this.request("GET", `/v1/projects/${projectId}/deployments/latest`),
|
|
194
244
|
rollback: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/rollback`, opts ?? {}),
|
|
@@ -207,6 +257,19 @@ class Novence {
|
|
|
207
257
|
force: input.force,
|
|
208
258
|
});
|
|
209
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
|
+
};
|
|
210
273
|
domains = {
|
|
211
274
|
configure: (projectId, hostname, input) => this.request("POST", `/v1/projects/${projectId}/domains`, {
|
|
212
275
|
hostname,
|
|
@@ -237,6 +300,15 @@ class Novence {
|
|
|
237
300
|
};
|
|
238
301
|
billing = {
|
|
239
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 }),
|
|
240
312
|
checkout: (input) => this.request("POST", "/v1/billing/checkout", input),
|
|
241
313
|
portal: (input = {}) => this.request("POST", "/v1/billing/portal", input),
|
|
242
314
|
/**
|
|
@@ -299,6 +371,50 @@ class Novence {
|
|
|
299
371
|
};
|
|
300
372
|
}
|
|
301
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
|
+
}
|
|
302
418
|
function withMethod(attribution, method) {
|
|
303
419
|
return { ...attribution, method: attribution?.method ?? method };
|
|
304
420
|
}
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -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
|
-
|
|
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;
|
|
@@ -40,6 +47,30 @@ export interface Project {
|
|
|
40
47
|
createdAt?: string;
|
|
41
48
|
updatedAt?: string;
|
|
42
49
|
}
|
|
50
|
+
/** Result of `projects.delete`. Calling it on an already-deleted project returns `alreadyDeleted: true`. */
|
|
51
|
+
export interface ProjectDeleteResult {
|
|
52
|
+
deleted: true;
|
|
53
|
+
alreadyDeleted: boolean;
|
|
54
|
+
project: {
|
|
55
|
+
id: string;
|
|
56
|
+
name: string;
|
|
57
|
+
suffix: string;
|
|
58
|
+
url: string;
|
|
59
|
+
customDomain: string | null;
|
|
60
|
+
};
|
|
61
|
+
deletedAt: string;
|
|
62
|
+
/** Custom-domain hosts unmapped at the edge by this call. */
|
|
63
|
+
customDomainHostsReleased: string[];
|
|
64
|
+
/** Site files are erased after the response unless the purge already finished. */
|
|
65
|
+
storage: {
|
|
66
|
+
status: "purged";
|
|
67
|
+
objectsDeleted: number;
|
|
68
|
+
} | {
|
|
69
|
+
status: "purging";
|
|
70
|
+
};
|
|
71
|
+
/** Edge cleanup steps that failed. Call `projects.delete` again to retry them. */
|
|
72
|
+
warnings: string[];
|
|
73
|
+
}
|
|
43
74
|
/**
|
|
44
75
|
* Quality-gate payload. When `skipped` is true (unverified accounts), `passed`
|
|
45
76
|
* is null — do not treat that as checks having passed.
|
|
@@ -50,11 +81,70 @@ export interface ChecksResults {
|
|
|
50
81
|
reason?: string;
|
|
51
82
|
/** Non-blocking findings, e.g. low Lighthouse performance while `enforcePerformance` is off. */
|
|
52
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;
|
|
53
88
|
[key: string]: unknown;
|
|
54
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
|
+
}
|
|
55
139
|
export interface Deployment {
|
|
56
140
|
id: string;
|
|
57
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;
|
|
58
148
|
phase?: DeploymentPhase;
|
|
59
149
|
/** 1-based place in the check-runner queue while `status` is `queued`; null otherwise. */
|
|
60
150
|
queuePosition?: number | null;
|
|
@@ -157,6 +247,27 @@ export interface Quotas {
|
|
|
157
247
|
/** Extra collaborators per project (owner excluded). Free/unverified is 0. */
|
|
158
248
|
teamSeats: number;
|
|
159
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
|
+
}
|
|
160
271
|
export interface ProjectUsage {
|
|
161
272
|
/** Prefer storage_bytes over storage_gb for exact accounting. */
|
|
162
273
|
storage_bytes: number;
|
|
@@ -234,6 +345,7 @@ export interface AccountSnapshot {
|
|
|
234
345
|
emailVerified?: boolean;
|
|
235
346
|
quotas?: Quotas;
|
|
236
347
|
usage?: Record<string, number>;
|
|
348
|
+
spendLimit?: SpendLimitStatus;
|
|
237
349
|
projects?: Array<Record<string, unknown>>;
|
|
238
350
|
subscription?: {
|
|
239
351
|
id: string;
|
|
@@ -302,6 +414,14 @@ export declare class Novence {
|
|
|
302
414
|
}) => Promise<{
|
|
303
415
|
project: Project;
|
|
304
416
|
}>;
|
|
417
|
+
/**
|
|
418
|
+
* Permanently delete a project (owner only, account key). Irreversible: the site goes
|
|
419
|
+
* offline on every host and its files are erased. `confirm` must equal the project's
|
|
420
|
+
* exact name or suffix.
|
|
421
|
+
*/
|
|
422
|
+
delete: (id: string, input: {
|
|
423
|
+
confirm: string;
|
|
424
|
+
}) => Promise<ProjectDeleteResult>;
|
|
305
425
|
usage: (id: string) => Promise<{
|
|
306
426
|
projectId: string;
|
|
307
427
|
period: {
|
|
@@ -358,14 +478,33 @@ export declare class Novence {
|
|
|
358
478
|
uploadBuffer: (projectId: string, path: string, contentType: string | undefined, body: ArrayBuffer | Uint8Array) => Promise<{
|
|
359
479
|
file: StagingFile;
|
|
360
480
|
}>;
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
uploaded: string[];
|
|
481
|
+
list: (projectId: string) => Promise<{
|
|
482
|
+
files: StagingFile[];
|
|
364
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;
|
|
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>;
|
|
365
498
|
};
|
|
366
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
|
+
*/
|
|
367
505
|
create: (projectId: string, opts?: {
|
|
368
506
|
force?: boolean;
|
|
507
|
+
source?: Partial<DeploySource>;
|
|
369
508
|
}) => Promise<{
|
|
370
509
|
deployment: Deployment;
|
|
371
510
|
}>;
|
|
@@ -388,6 +527,29 @@ export declare class Novence {
|
|
|
388
527
|
projectId?: string;
|
|
389
528
|
force?: boolean;
|
|
390
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
|
+
};
|
|
391
553
|
domains: {
|
|
392
554
|
configure: (projectId: string, hostname: string, input?: {
|
|
393
555
|
primary?: "www" | "apex";
|
|
@@ -455,7 +617,17 @@ export declare class Novence {
|
|
|
455
617
|
quotas: Quotas;
|
|
456
618
|
usage: Record<string, number>;
|
|
457
619
|
bandwidthMetering?: string;
|
|
620
|
+
spendLimit?: SpendLimitStatus;
|
|
458
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>;
|
|
459
631
|
checkout: (input: {
|
|
460
632
|
successUrl?: string;
|
|
461
633
|
cancelUrl?: string;
|
|
@@ -530,6 +702,17 @@ export declare class Novence {
|
|
|
530
702
|
}>;
|
|
531
703
|
};
|
|
532
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>;
|
|
533
716
|
export interface SignupAttributionInput {
|
|
534
717
|
method?: "web" | "mcp" | "cli" | "sdk" | "api";
|
|
535
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
|
-
|
|
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
|
-
|
|
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
|
}
|
|
@@ -98,6 +110,12 @@ export class Novence {
|
|
|
98
110
|
list: () => this.request("GET", "/v1/projects"),
|
|
99
111
|
get: (id) => this.request("GET", `/v1/projects/${id}`),
|
|
100
112
|
update: (id, input) => this.request("PATCH", `/v1/projects/${id}`, input),
|
|
113
|
+
/**
|
|
114
|
+
* Permanently delete a project (owner only, account key). Irreversible: the site goes
|
|
115
|
+
* offline on every host and its files are erased. `confirm` must equal the project's
|
|
116
|
+
* exact name or suffix.
|
|
117
|
+
*/
|
|
118
|
+
delete: (id, input) => this.request("DELETE", `/v1/projects/${id}`, { confirm: input.confirm }),
|
|
101
119
|
usage: (id) => this.request("GET", `/v1/projects/${id}/usage`),
|
|
102
120
|
analytics: (id, range) => {
|
|
103
121
|
const q = new URLSearchParams();
|
|
@@ -145,12 +163,21 @@ export class Novence {
|
|
|
145
163
|
throw new NovenceError(`Upload failed for ${path}`, put.status);
|
|
146
164
|
return this.files.confirm(projectId, path, type);
|
|
147
165
|
},
|
|
148
|
-
|
|
149
|
-
|
|
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 = {}) => {
|
|
150
177
|
function walk(current) {
|
|
151
178
|
const out = [];
|
|
152
179
|
for (const name of readdirSync(current)) {
|
|
153
|
-
if (name.startsWith("."))
|
|
180
|
+
if (name.startsWith(".") && name !== ".well-known")
|
|
154
181
|
continue;
|
|
155
182
|
const full = join(current, name);
|
|
156
183
|
if (statSync(full).isDirectory())
|
|
@@ -172,10 +199,32 @@ export class Novence {
|
|
|
172
199
|
await this.files.uploadBuffer(projectId, rel, contentType, body);
|
|
173
200
|
uploaded.push(rel);
|
|
174
201
|
}
|
|
175
|
-
|
|
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 };
|
|
176
220
|
},
|
|
177
221
|
};
|
|
178
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
|
+
*/
|
|
179
228
|
create: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/deployments`, opts ?? {}),
|
|
180
229
|
latest: (projectId) => this.request("GET", `/v1/projects/${projectId}/deployments/latest`),
|
|
181
230
|
rollback: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/rollback`, opts ?? {}),
|
|
@@ -194,6 +243,19 @@ export class Novence {
|
|
|
194
243
|
force: input.force,
|
|
195
244
|
});
|
|
196
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
|
+
};
|
|
197
259
|
domains = {
|
|
198
260
|
configure: (projectId, hostname, input) => this.request("POST", `/v1/projects/${projectId}/domains`, {
|
|
199
261
|
hostname,
|
|
@@ -224,6 +286,15 @@ export class Novence {
|
|
|
224
286
|
};
|
|
225
287
|
billing = {
|
|
226
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 }),
|
|
227
298
|
checkout: (input) => this.request("POST", "/v1/billing/checkout", input),
|
|
228
299
|
portal: (input = {}) => this.request("POST", "/v1/billing/portal", input),
|
|
229
300
|
/**
|
|
@@ -285,6 +356,50 @@ export class Novence {
|
|
|
285
356
|
revoke: (id, opts = {}) => this.request("DELETE", `/v1/api-keys/${id}${opts.force ? "?force=true" : ""}`),
|
|
286
357
|
};
|
|
287
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
|
+
}
|
|
288
403
|
function withMethod(attribution, method) {
|
|
289
404
|
return { ...attribution, method: attribution?.method ?? method };
|
|
290
405
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@novence/sdk",
|
|
3
|
-
"version": "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",
|