@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 +47 -3
- package/dist/cjs/index.d.ts +155 -4
- package/dist/cjs/index.js +116 -6
- package/dist/esm/index.d.ts +155 -4
- package/dist/esm/index.js +115 -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;
|
|
@@ -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
|
-
|
|
394
|
-
|
|
395
|
-
|
|
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
|
-
|
|
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
|
}
|
|
@@ -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
|
-
|
|
168
|
-
|
|
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
|
-
|
|
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
|
}
|
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;
|
|
@@ -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
|
-
|
|
394
|
-
|
|
395
|
-
|
|
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
|
-
|
|
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
|
}
|
|
@@ -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
|
-
|
|
155
|
-
|
|
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
|
-
|
|
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.
|
|
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",
|