@novence/sdk 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,7 +8,13 @@ Create a project, upload HTML/CSS/JS, run quality checks, and publish to the edg
8
8
  npm install @novence/sdk
9
9
  ```
10
10
 
11
- Requires Node 18+ (uses the global `fetch`).
11
+ Requires Node 18+ (uses the global `fetch`). Ships both ESM and CommonJS, so
12
+ `import` and `require` both work with no configuration.
13
+
14
+ ```ts
15
+ import { Novence } from "@novence/sdk"; // ESM
16
+ const { Novence } = require("@novence/sdk"); // CommonJS
17
+ ```
12
18
 
13
19
  ## Quick start
14
20
 
@@ -95,6 +101,27 @@ call at a different control plane — useful when running the API locally.
95
101
  Standalone helpers for the pre-auth flow: `bootstrapAccount`, `verifyEmail`,
96
102
  `resendVerification`, `reissueApiKey`.
97
103
 
104
+ ## Identity checks
105
+
106
+ Prefer `isNovenceClient()` over `instanceof Novence`:
107
+
108
+ ```ts
109
+ import { isNovenceClient } from "@novence/sdk";
110
+
111
+ if (isNovenceClient(value)) {
112
+ // value is a Novence client
113
+ }
114
+ ```
115
+
116
+ Because this package ships dual ESM/CommonJS builds, a process that loads both
117
+ copies gets two distinct `Novence` classes and `instanceof` fails across that
118
+ boundary — the "dual package hazard". `isNovenceClient` tests a `Symbol.for`
119
+ brand, which is shared by every copy, so it works regardless of how the client
120
+ was constructed.
121
+
122
+ For the same reason the base URL is resolved on each call rather than snapshotted
123
+ at import, so two copies can never disagree about which control plane to hit.
124
+
98
125
  ## Security
99
126
 
100
127
  `nv_` keys are server-side credentials. Never ship one in browser HTML, a URL, or a git commit. Read it from the environment.
@@ -1,8 +1,7 @@
1
- /**
2
- * Public control plane. Override per-call, or globally with NOVENCE_BASE_URL
3
- * (useful when pointing the SDK at a local API during development).
4
- */
5
- export declare const DEFAULT_BASE_URL: string;
1
+ /** Public control plane. */
2
+ export declare const DEFAULT_BASE_URL = "https://api.novence.ai";
3
+ /** True for a Novence client from any copy of this module. */
4
+ export declare function isNovenceClient(value: unknown): value is Novence;
6
5
  export interface NovenceOptions {
7
6
  apiKey: string;
8
7
  baseUrl?: string;
@@ -104,6 +103,22 @@ export interface FormSubmission {
104
103
  payload: Record<string, unknown>;
105
104
  createdAt: string;
106
105
  }
106
+ export interface ApiKey {
107
+ id: string;
108
+ /** First 12 chars, e.g. nv_live_ab12. The key itself is never returned. */
109
+ keyPrefix: string;
110
+ /** "account", "project", or "member:{email}". */
111
+ name: string;
112
+ projectId: string | null;
113
+ /** Account keys have a null projectId. */
114
+ scope: "account" | "project";
115
+ permissions?: Record<string, boolean>;
116
+ lastUsedAt?: string | null;
117
+ revokedAt?: string | null;
118
+ createdAt?: string;
119
+ /** True for the key this client is authenticating with. */
120
+ current: boolean;
121
+ }
107
122
  export interface Quotas {
108
123
  projects: number;
109
124
  storageGb: number;
@@ -366,7 +381,26 @@ export declare class Novence {
366
381
  }>;
367
382
  };
368
383
  apiKeys: {
369
- revoke: (id: string) => Promise<{
384
+ /**
385
+ * List keys on the account. Never includes the key or its hash — match on
386
+ * `keyPrefix`, and check `current` before revoking.
387
+ */
388
+ list: (opts?: {
389
+ projectId?: string;
390
+ includeRevoked?: boolean;
391
+ }) => Promise<{
392
+ keys: ApiKey[];
393
+ }>;
394
+ /**
395
+ * Revoke a key. Idempotent.
396
+ *
397
+ * Rejects with 409 when `id` is the key this client authenticates with;
398
+ * pass `force` to override, after which recovery needs `reissueApiKey`
399
+ * with an email OTP.
400
+ */
401
+ revoke: (id: string, opts?: {
402
+ force?: boolean;
403
+ }) => Promise<{
370
404
  id: string;
371
405
  revoked: boolean;
372
406
  }>;
@@ -0,0 +1,287 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.Novence = exports.DEFAULT_BASE_URL = void 0;
4
+ exports.isNovenceClient = isNovenceClient;
5
+ exports.bootstrapAccount = bootstrapAccount;
6
+ exports.verifyEmail = verifyEmail;
7
+ exports.resendVerification = resendVerification;
8
+ exports.reissueApiKey = reissueApiKey;
9
+ const node_fs_1 = require("node:fs");
10
+ const node_path_1 = require("node:path");
11
+ /** Public control plane. */
12
+ exports.DEFAULT_BASE_URL = "https://api.novence.ai";
13
+ /**
14
+ * Resolved per call, not snapshotted at import time, so setting
15
+ * NOVENCE_BASE_URL after import still takes effect — and two copies of this
16
+ * module (see `isNovenceClient`) can never disagree on the target.
17
+ */
18
+ function resolveBaseUrl(explicit) {
19
+ const raw = explicit ?? process.env.NOVENCE_BASE_URL ?? exports.DEFAULT_BASE_URL;
20
+ return raw.replace(/\/$/, "");
21
+ }
22
+ /**
23
+ * Brand for cross-copy identity checks.
24
+ *
25
+ * A package shipped as both ESM and CommonJS can be loaded twice in one process
26
+ * (the "dual package hazard"), which yields two distinct `Novence` classes and
27
+ * makes `instanceof` fail across the boundary. `Symbol.for` is registry-global,
28
+ * so this brand is shared by every copy. Prefer `isNovenceClient()` over
29
+ * `instanceof Novence`.
30
+ */
31
+ const CLIENT_BRAND = Symbol.for("novence.sdk.client");
32
+ /** True for a Novence client from any copy of this module. */
33
+ function isNovenceClient(value) {
34
+ return (typeof value === "object" &&
35
+ value !== null &&
36
+ value[CLIENT_BRAND] === true);
37
+ }
38
+ const MIME_BY_EXT = {
39
+ ".html": "text/html; charset=utf-8",
40
+ ".css": "text/css; charset=utf-8",
41
+ ".js": "text/javascript; charset=utf-8",
42
+ ".mjs": "text/javascript; charset=utf-8",
43
+ ".map": "application/json",
44
+ ".json": "application/json",
45
+ ".svg": "image/svg+xml",
46
+ ".png": "image/png",
47
+ ".jpg": "image/jpeg",
48
+ ".jpeg": "image/jpeg",
49
+ ".gif": "image/gif",
50
+ ".webp": "image/webp",
51
+ ".ico": "image/x-icon",
52
+ ".woff": "font/woff",
53
+ ".woff2": "font/woff2",
54
+ ".ttf": "font/ttf",
55
+ ".txt": "text/plain; charset=utf-8",
56
+ ".xml": "application/xml",
57
+ ".webmanifest": "application/manifest+json",
58
+ ".mp4": "video/mp4",
59
+ ".webm": "video/webm",
60
+ ".mov": "video/quicktime",
61
+ };
62
+ class Novence {
63
+ apiKey;
64
+ baseUrl;
65
+ constructor(opts) {
66
+ this.apiKey = opts.apiKey;
67
+ this.baseUrl = resolveBaseUrl(opts.baseUrl);
68
+ Object.defineProperty(this, CLIENT_BRAND, {
69
+ value: true,
70
+ enumerable: false,
71
+ writable: false,
72
+ });
73
+ }
74
+ async request(method, path, body) {
75
+ const res = await fetch(`${this.baseUrl}${path}`, {
76
+ method,
77
+ headers: {
78
+ Authorization: `Bearer ${this.apiKey}`,
79
+ "Content-Type": "application/json",
80
+ },
81
+ body: body === undefined ? undefined : JSON.stringify(body),
82
+ });
83
+ const data = (await res.json());
84
+ if (!res.ok) {
85
+ throw new Error(data.error ?? `HTTP ${res.status}`);
86
+ }
87
+ return data;
88
+ }
89
+ projects = {
90
+ create: (input) => this.request("POST", "/v1/projects", input),
91
+ list: () => this.request("GET", "/v1/projects"),
92
+ get: (id) => this.request("GET", `/v1/projects/${id}`),
93
+ update: (id, input) => this.request("PATCH", `/v1/projects/${id}`, input),
94
+ usage: (id) => this.request("GET", `/v1/projects/${id}/usage`),
95
+ analytics: (id, range) => {
96
+ const q = new URLSearchParams();
97
+ if (range?.from)
98
+ q.set("from", range.from);
99
+ if (range?.to)
100
+ q.set("to", range.to);
101
+ const qs = q.toString();
102
+ return this.request("GET", `/v1/projects/${id}/analytics${qs ? `?${qs}` : ""}`);
103
+ },
104
+ };
105
+ files = {
106
+ getUploadUrl: (projectId, path, contentType) => this.request("POST", `/v1/projects/${projectId}/uploads`, {
107
+ path,
108
+ contentType,
109
+ }),
110
+ getUploadUrlsBatch: (projectId, files) => this.request("POST", `/v1/projects/${projectId}/uploads/batch`, { files }),
111
+ confirm: (projectId, path, contentType) => this.request("POST", `/v1/projects/${projectId}/uploads/confirm`, { path, contentType }),
112
+ confirmBatch: (projectId, files) => this.request("POST", `/v1/projects/${projectId}/uploads/confirm-batch`, { files }),
113
+ uploadBuffer: async (projectId, path, contentType, body) => {
114
+ const type = contentType || MIME_BY_EXT[(0, node_path_1.extname)(path).toLowerCase()] || "application/octet-stream";
115
+ const { uploadUrl } = await this.files.getUploadUrl(projectId, path, type);
116
+ const bytes = body instanceof ArrayBuffer
117
+ ? new Uint8Array(body)
118
+ : new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
119
+ const copy = new Uint8Array(bytes.byteLength);
120
+ copy.set(bytes);
121
+ const put = await fetch(uploadUrl, {
122
+ method: "PUT",
123
+ headers: { "Content-Type": type },
124
+ body: new Blob([copy], { type }),
125
+ });
126
+ if (!put.ok)
127
+ throw new Error(`Upload failed: ${put.status}`);
128
+ return this.files.confirm(projectId, path, type);
129
+ },
130
+ /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
131
+ uploadDir: async (projectId, dir) => {
132
+ function walk(current) {
133
+ const out = [];
134
+ for (const name of (0, node_fs_1.readdirSync)(current)) {
135
+ if (name.startsWith("."))
136
+ continue;
137
+ const full = (0, node_path_1.join)(current, name);
138
+ if ((0, node_fs_1.statSync)(full).isDirectory())
139
+ out.push(...walk(full));
140
+ else
141
+ out.push(full);
142
+ }
143
+ return out;
144
+ }
145
+ const uploaded = [];
146
+ for (const full of walk(dir)) {
147
+ const rel = "/" + (0, node_path_1.relative)(dir, full).split("\\").join("/");
148
+ const contentType = MIME_BY_EXT[(0, node_path_1.extname)(full).toLowerCase()];
149
+ if (!contentType)
150
+ continue;
151
+ const body = (0, node_fs_1.readFileSync)(full);
152
+ await this.files.uploadBuffer(projectId, rel, contentType, body);
153
+ uploaded.push(rel);
154
+ }
155
+ return { uploaded };
156
+ },
157
+ };
158
+ deployments = {
159
+ create: (projectId, opts) => this.request("POST", `/v1/projects/${projectId}/deployments`, opts ?? {}),
160
+ latest: (projectId) => this.request("GET", `/v1/projects/${projectId}/deployments/latest`),
161
+ };
162
+ domains = {
163
+ configure: (projectId, hostname) => this.request("POST", `/v1/projects/${projectId}/domains`, {
164
+ hostname,
165
+ }),
166
+ status: (projectId) => this.request("GET", `/v1/projects/${projectId}/domains`),
167
+ };
168
+ forms = {
169
+ create: (projectId, input) => this.request("POST", `/v1/projects/${projectId}/forms`, input),
170
+ list: (projectId) => this.request("GET", `/v1/projects/${projectId}/forms`),
171
+ get: (projectId, formId) => this.request("GET", `/v1/projects/${projectId}/forms/${formId}`),
172
+ update: (projectId, formId, input) => this.request("PATCH", `/v1/projects/${projectId}/forms/${formId}`, input),
173
+ delete: (projectId, formId) => this.request("DELETE", `/v1/projects/${projectId}/forms/${formId}`),
174
+ listSubmissions: (projectId, formId, opts) => {
175
+ const q = new URLSearchParams();
176
+ if (opts?.limit != null)
177
+ q.set("limit", String(opts.limit));
178
+ if (opts?.offset != null)
179
+ q.set("offset", String(opts.offset));
180
+ const qs = q.toString();
181
+ return this.request("GET", `/v1/projects/${projectId}/forms/${formId}/submissions${qs ? `?${qs}` : ""}`);
182
+ },
183
+ deleteSubmission: (projectId, formId, submissionId) => this.request("DELETE", `/v1/projects/${projectId}/forms/${formId}/submissions/${submissionId}`),
184
+ };
185
+ billing = {
186
+ quotas: () => this.request("GET", "/v1/billing/quotas"),
187
+ checkout: (input) => this.request("POST", "/v1/billing/checkout", input),
188
+ portal: (input = {}) => this.request("POST", "/v1/billing/portal", input),
189
+ /**
190
+ * Start MPP SPT subscription (returns 402 challenge for agents).
191
+ * Completing Payment creates the same monthly Stripe subscription as Checkout.
192
+ */
193
+ mppUpgrade: async (input = {}) => {
194
+ const res = await fetch(`${this.baseUrl}/v1/billing/mpp`, {
195
+ method: "POST",
196
+ headers: {
197
+ Authorization: `Bearer ${this.apiKey}`,
198
+ "Content-Type": "application/json",
199
+ Accept: "application/json",
200
+ },
201
+ body: JSON.stringify({ plan: input.plan ?? "pro" }),
202
+ });
203
+ const www = res.headers.get("www-authenticate");
204
+ const data = await res.json().catch(() => ({}));
205
+ return {
206
+ status: res.status,
207
+ wwwAuthenticate: www,
208
+ data,
209
+ };
210
+ },
211
+ };
212
+ account = {
213
+ get: () => this.request("GET", "/v1/account"),
214
+ consoleKit: () => this.request("GET", "/v1/account/console-kit"),
215
+ createSession: () => this.request("POST", "/v1/account/sessions"),
216
+ revokeSession: () => this.request("DELETE", "/v1/account/sessions/current"),
217
+ };
218
+ apiKeys = {
219
+ /**
220
+ * List keys on the account. Never includes the key or its hash — match on
221
+ * `keyPrefix`, and check `current` before revoking.
222
+ */
223
+ list: (opts = {}) => {
224
+ const q = new URLSearchParams();
225
+ if (opts.projectId)
226
+ q.set("projectId", opts.projectId);
227
+ if (opts.includeRevoked)
228
+ q.set("includeRevoked", "true");
229
+ const qs = q.toString();
230
+ return this.request("GET", `/v1/api-keys${qs ? `?${qs}` : ""}`);
231
+ },
232
+ /**
233
+ * Revoke a key. Idempotent.
234
+ *
235
+ * Rejects with 409 when `id` is the key this client authenticates with;
236
+ * pass `force` to override, after which recovery needs `reissueApiKey`
237
+ * with an email OTP.
238
+ */
239
+ revoke: (id, opts = {}) => this.request("DELETE", `/v1/api-keys/${id}${opts.force ? "?force=true" : ""}`),
240
+ };
241
+ }
242
+ exports.Novence = Novence;
243
+ async function bootstrapAccount(email, baseUrl) {
244
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/bootstrap`, {
245
+ method: "POST",
246
+ headers: { "Content-Type": "application/json" },
247
+ body: JSON.stringify({ email }),
248
+ });
249
+ const data = (await res.json());
250
+ if (!res.ok)
251
+ throw new Error(data.error ?? `HTTP ${res.status}`);
252
+ return data;
253
+ }
254
+ async function verifyEmail(email, code, baseUrl) {
255
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/verify-email`, {
256
+ method: "POST",
257
+ headers: { "Content-Type": "application/json" },
258
+ body: JSON.stringify({ email, code }),
259
+ });
260
+ const data = (await res.json());
261
+ if (!res.ok)
262
+ throw new Error(data.error ?? `HTTP ${res.status}`);
263
+ return data;
264
+ }
265
+ async function resendVerification(email, baseUrl) {
266
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/resend-verification`, {
267
+ method: "POST",
268
+ headers: { "Content-Type": "application/json" },
269
+ body: JSON.stringify({ email }),
270
+ });
271
+ const data = (await res.json());
272
+ if (!res.ok)
273
+ throw new Error(data.error ?? `HTTP ${res.status}`);
274
+ return data;
275
+ }
276
+ /** Recover a lost account API key with email OTP (after resend-verification). */
277
+ async function reissueApiKey(email, code, baseUrl) {
278
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/reissue-key`, {
279
+ method: "POST",
280
+ headers: { "Content-Type": "application/json" },
281
+ body: JSON.stringify({ email, code }),
282
+ });
283
+ const data = (await res.json());
284
+ if (!res.ok)
285
+ throw new Error(data.error ?? `HTTP ${res.status}`);
286
+ return data;
287
+ }
@@ -0,0 +1,3 @@
1
+ {
2
+ "type": "commonjs"
3
+ }
@@ -0,0 +1,432 @@
1
+ /** Public control plane. */
2
+ export declare const DEFAULT_BASE_URL = "https://api.novence.ai";
3
+ /** True for a Novence client from any copy of this module. */
4
+ export declare function isNovenceClient(value: unknown): value is Novence;
5
+ export interface NovenceOptions {
6
+ apiKey: string;
7
+ baseUrl?: string;
8
+ }
9
+ /** Narrowed lifecycle used by `deployment.phase`. */
10
+ export type DeploymentPhase = "queued" | "checking" | "promoting" | "live" | "failed";
11
+ /** Raw `deployment.status`; `pending` collapses to the `queued` phase. */
12
+ export type DeploymentStatus = DeploymentPhase | "pending";
13
+ export interface Project {
14
+ id: string;
15
+ name: string;
16
+ /** Subdomain label for https://{suffix}.novence.ai/ */
17
+ suffix: string;
18
+ url: string;
19
+ /** Project lifecycle (active/deleted/suspended) — NOT deploy status. */
20
+ status: string;
21
+ /** @deprecated Use `suffix`. */
22
+ randomSuffix?: string;
23
+ description?: string | null;
24
+ customDomain?: string | null;
25
+ customDomainStatus?: string;
26
+ analyticsEnabled?: boolean;
27
+ createdAt?: string;
28
+ updatedAt?: string;
29
+ }
30
+ /**
31
+ * Quality-gate payload. When `skipped` is true (unverified accounts), `passed`
32
+ * is null — do not treat that as checks having passed.
33
+ */
34
+ export interface ChecksResults {
35
+ passed: boolean | null;
36
+ skipped?: boolean;
37
+ reason?: string;
38
+ [key: string]: unknown;
39
+ }
40
+ export interface Deployment {
41
+ id: string;
42
+ status: DeploymentStatus;
43
+ phase?: DeploymentPhase;
44
+ checksResults?: ChecksResults | null;
45
+ checksUrl?: string;
46
+ errorMessage?: string | null;
47
+ previewUrl?: string;
48
+ liveUrl?: string | null;
49
+ createdAt?: string;
50
+ }
51
+ export interface UploadPresign {
52
+ path: string;
53
+ uploadUrl: string;
54
+ s3Key: string;
55
+ contentType: string;
56
+ expiresIn: number;
57
+ }
58
+ export interface StagingFile {
59
+ id: string;
60
+ projectId: string;
61
+ path: string;
62
+ s3Key: string;
63
+ sizeBytes: number;
64
+ contentType: string;
65
+ etag?: string | null;
66
+ }
67
+ export interface ConfirmBatchResponse {
68
+ files: StagingFile[];
69
+ /** Failed paths. Empty on full success. Retry these only. */
70
+ errors: Array<{
71
+ path: string;
72
+ error: string;
73
+ }>;
74
+ }
75
+ export type FormFieldType = "text" | "email" | "tel" | "url" | "textarea" | "number" | "select" | "checkbox" | "hidden";
76
+ export interface FormField {
77
+ name: string;
78
+ type: FormFieldType;
79
+ required?: boolean;
80
+ label?: string;
81
+ options?: string[];
82
+ }
83
+ export interface FormSubmitUrls {
84
+ edgePath: string;
85
+ edgeUrl: string;
86
+ publicApiUrl: string;
87
+ }
88
+ export interface Form {
89
+ id: string;
90
+ projectId: string;
91
+ name: string;
92
+ slug: string;
93
+ fields: FormField[];
94
+ notifyEmail: string | null;
95
+ honeypotField: string;
96
+ status: string;
97
+ createdAt: string;
98
+ updatedAt: string;
99
+ submit: FormSubmitUrls;
100
+ }
101
+ export interface FormSubmission {
102
+ id: string;
103
+ payload: Record<string, unknown>;
104
+ createdAt: string;
105
+ }
106
+ export interface ApiKey {
107
+ id: string;
108
+ /** First 12 chars, e.g. nv_live_ab12. The key itself is never returned. */
109
+ keyPrefix: string;
110
+ /** "account", "project", or "member:{email}". */
111
+ name: string;
112
+ projectId: string | null;
113
+ /** Account keys have a null projectId. */
114
+ scope: "account" | "project";
115
+ permissions?: Record<string, boolean>;
116
+ lastUsedAt?: string | null;
117
+ revokedAt?: string | null;
118
+ createdAt?: string;
119
+ /** True for the key this client is authenticating with. */
120
+ current: boolean;
121
+ }
122
+ export interface Quotas {
123
+ projects: number;
124
+ storageGb: number;
125
+ bandwidthGb: number;
126
+ deploysPerMonth: number;
127
+ /** Included check MINUTES per month (same unit as usage.check_minutes). */
128
+ checkRuns: number;
129
+ customDomains: number;
130
+ formSubmissionsPerMonth: number;
131
+ /** Extra collaborators per project (owner excluded). Free/unverified is 0. */
132
+ teamSeats: number;
133
+ }
134
+ export interface ProjectUsage {
135
+ /** Prefer storage_bytes over storage_gb for exact accounting. */
136
+ storage_bytes: number;
137
+ storage_gb: number;
138
+ deploys_count: number;
139
+ check_minutes: number;
140
+ custom_domains_count: number;
141
+ form_submissions: number;
142
+ bandwidth_gb: number;
143
+ }
144
+ export interface Analytics {
145
+ projectId: string;
146
+ suffix: string;
147
+ enabled?: boolean;
148
+ period: {
149
+ from: string;
150
+ to: string;
151
+ };
152
+ retentionDays: number;
153
+ unavailable?: boolean;
154
+ reason?: string;
155
+ totals: {
156
+ pageviews: number;
157
+ notFound: number;
158
+ };
159
+ days?: Array<{
160
+ day: string;
161
+ pageviews: number;
162
+ }>;
163
+ topPages?: Array<{
164
+ path: string;
165
+ pageviews: number;
166
+ }>;
167
+ }
168
+ /** Not schematised in openapi.yaml — known fields only. */
169
+ export interface DomainConfigureResult {
170
+ hosts?: string[];
171
+ canonicalHost?: string;
172
+ redirect?: boolean;
173
+ primaryPreference?: "www" | "apex" | null;
174
+ instructions?: {
175
+ summary?: string;
176
+ maxRecords?: number;
177
+ cnameTarget?: string;
178
+ records?: Array<Record<string, unknown>>;
179
+ [key: string]: unknown;
180
+ };
181
+ [key: string]: unknown;
182
+ }
183
+ /** Not schematised in openapi.yaml — known fields only. */
184
+ export interface DomainStatus {
185
+ hostname?: string | null;
186
+ status?: string;
187
+ [key: string]: unknown;
188
+ }
189
+ /** Not schematised in openapi.yaml — known fields only. */
190
+ export interface AccountSnapshot {
191
+ plan?: string;
192
+ emailVerified?: boolean;
193
+ quotas?: Quotas;
194
+ usage?: Record<string, number>;
195
+ projects?: Array<Record<string, unknown>>;
196
+ subscription?: {
197
+ id: string;
198
+ status: string;
199
+ currentPeriodEnd: string | null;
200
+ cancelAtPeriodEnd: boolean;
201
+ } | null;
202
+ [key: string]: unknown;
203
+ }
204
+ /** Not schematised in openapi.yaml — known fields only. */
205
+ export interface ConsoleKit {
206
+ htmlTemplate?: string;
207
+ snapshot?: AccountSnapshot;
208
+ [key: string]: unknown;
209
+ }
210
+ export declare class Novence {
211
+ readonly apiKey: string;
212
+ readonly baseUrl: string;
213
+ constructor(opts: NovenceOptions);
214
+ private request;
215
+ projects: {
216
+ create: (input: {
217
+ name: string;
218
+ description?: string;
219
+ }) => Promise<{
220
+ project: Project;
221
+ projectApiKey: string;
222
+ url: string;
223
+ }>;
224
+ list: () => Promise<{
225
+ projects: Project[];
226
+ }>;
227
+ get: (id: string) => Promise<{
228
+ project: Project;
229
+ }>;
230
+ update: (id: string, input: {
231
+ name?: string;
232
+ description?: string;
233
+ checkThresholds?: Record<string, unknown>;
234
+ analyticsEnabled?: boolean;
235
+ }) => Promise<{
236
+ project: Project;
237
+ }>;
238
+ usage: (id: string) => Promise<{
239
+ projectId: string;
240
+ period: {
241
+ start: string;
242
+ };
243
+ usage: ProjectUsage;
244
+ quotas: Quotas;
245
+ bandwidthMetering: "live" | "pending";
246
+ }>;
247
+ analytics: (id: string, range?: {
248
+ from?: string;
249
+ to?: string;
250
+ }) => Promise<Analytics>;
251
+ };
252
+ files: {
253
+ getUploadUrl: (projectId: string, path: string, contentType?: string) => Promise<UploadPresign>;
254
+ getUploadUrlsBatch: (projectId: string, files: Array<{
255
+ path: string;
256
+ contentType?: string;
257
+ }>) => Promise<{
258
+ uploads: UploadPresign[];
259
+ }>;
260
+ confirm: (projectId: string, path: string, contentType?: string) => Promise<{
261
+ file: StagingFile;
262
+ }>;
263
+ confirmBatch: (projectId: string, files: Array<{
264
+ path: string;
265
+ contentType?: string;
266
+ }>) => Promise<ConfirmBatchResponse>;
267
+ uploadBuffer: (projectId: string, path: string, contentType: string | undefined, body: ArrayBuffer | Uint8Array) => Promise<{
268
+ file: StagingFile;
269
+ }>;
270
+ /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
271
+ uploadDir: (projectId: string, dir: string) => Promise<{
272
+ uploaded: string[];
273
+ }>;
274
+ };
275
+ deployments: {
276
+ create: (projectId: string, opts?: {
277
+ force?: boolean;
278
+ }) => Promise<{
279
+ deployment: Deployment;
280
+ }>;
281
+ latest: (projectId: string) => Promise<{
282
+ deployment: Deployment;
283
+ }>;
284
+ };
285
+ domains: {
286
+ configure: (projectId: string, hostname: string) => Promise<DomainConfigureResult>;
287
+ status: (projectId: string) => Promise<DomainStatus>;
288
+ };
289
+ forms: {
290
+ create: (projectId: string, input: {
291
+ name: string;
292
+ slug?: string;
293
+ fields?: Array<{
294
+ name: string;
295
+ type: "text" | "email" | "tel" | "url" | "textarea" | "number" | "select" | "checkbox" | "hidden";
296
+ required?: boolean;
297
+ label?: string;
298
+ options?: string[];
299
+ }>;
300
+ notifyEmail?: string | null;
301
+ honeypotField?: string;
302
+ }) => Promise<{
303
+ form: Form;
304
+ }>;
305
+ list: (projectId: string) => Promise<{
306
+ forms: Form[];
307
+ }>;
308
+ get: (projectId: string, formId: string) => Promise<{
309
+ form: Form;
310
+ }>;
311
+ update: (projectId: string, formId: string, input: {
312
+ name?: string;
313
+ slug?: string;
314
+ fields?: FormField[];
315
+ notifyEmail?: string | null;
316
+ honeypotField?: string;
317
+ status?: "active" | "disabled";
318
+ }) => Promise<{
319
+ form: Form;
320
+ }>;
321
+ delete: (projectId: string, formId: string) => Promise<{
322
+ deleted: boolean;
323
+ formId: string;
324
+ }>;
325
+ listSubmissions: (projectId: string, formId: string, opts?: {
326
+ limit?: number;
327
+ offset?: number;
328
+ }) => Promise<{
329
+ formId: string;
330
+ total: number;
331
+ submissions: FormSubmission[];
332
+ }>;
333
+ deleteSubmission: (projectId: string, formId: string, submissionId: string) => Promise<{
334
+ deleted: boolean;
335
+ submissionId: string;
336
+ }>;
337
+ };
338
+ billing: {
339
+ quotas: () => Promise<{
340
+ plan: string;
341
+ emailVerified?: boolean;
342
+ quotas: Quotas;
343
+ usage: Record<string, number>;
344
+ bandwidthMetering?: string;
345
+ }>;
346
+ checkout: (input: {
347
+ successUrl?: string;
348
+ cancelUrl?: string;
349
+ plan?: "pro" | "scale";
350
+ }) => Promise<{
351
+ url: string | null;
352
+ id: string;
353
+ }>;
354
+ portal: (input?: {
355
+ returnUrl?: string;
356
+ }) => Promise<{
357
+ url: string;
358
+ }>;
359
+ /**
360
+ * Start MPP SPT subscription (returns 402 challenge for agents).
361
+ * Completing Payment creates the same monthly Stripe subscription as Checkout.
362
+ */
363
+ mppUpgrade: (input?: {
364
+ plan?: "pro" | "scale";
365
+ }) => Promise<{
366
+ status: number;
367
+ wwwAuthenticate: string | null;
368
+ data: any;
369
+ }>;
370
+ };
371
+ account: {
372
+ get: () => Promise<AccountSnapshot>;
373
+ consoleKit: () => Promise<ConsoleKit>;
374
+ createSession: () => Promise<{
375
+ token: string;
376
+ expiresAt: string;
377
+ scopes: string[];
378
+ }>;
379
+ revokeSession: () => Promise<{
380
+ revoked: boolean;
381
+ }>;
382
+ };
383
+ apiKeys: {
384
+ /**
385
+ * List keys on the account. Never includes the key or its hash — match on
386
+ * `keyPrefix`, and check `current` before revoking.
387
+ */
388
+ list: (opts?: {
389
+ projectId?: string;
390
+ includeRevoked?: boolean;
391
+ }) => Promise<{
392
+ keys: ApiKey[];
393
+ }>;
394
+ /**
395
+ * Revoke a key. Idempotent.
396
+ *
397
+ * Rejects with 409 when `id` is the key this client authenticates with;
398
+ * pass `force` to override, after which recovery needs `reissueApiKey`
399
+ * with an email OTP.
400
+ */
401
+ revoke: (id: string, opts?: {
402
+ force?: boolean;
403
+ }) => Promise<{
404
+ id: string;
405
+ revoked: boolean;
406
+ }>;
407
+ };
408
+ }
409
+ export declare function bootstrapAccount(email: string, baseUrl?: string): Promise<{
410
+ accountId: string;
411
+ apiKey: string;
412
+ plan: string;
413
+ emailVerificationRequired?: boolean;
414
+ verificationCode?: string;
415
+ }>;
416
+ export declare function verifyEmail(email: string, code: string, baseUrl?: string): Promise<{
417
+ accountId: string;
418
+ emailVerified: boolean;
419
+ alreadyVerified?: boolean;
420
+ }>;
421
+ export declare function resendVerification(email: string, baseUrl?: string): Promise<{
422
+ sent?: boolean;
423
+ emailVerificationRequired: boolean;
424
+ alreadyVerified?: boolean;
425
+ verificationCode?: string;
426
+ }>;
427
+ /** Recover a lost account API key with email OTP (after resend-verification). */
428
+ export declare function reissueApiKey(email: string, code: string, baseUrl?: string): Promise<{
429
+ accountId: string;
430
+ apiKey: string;
431
+ emailVerified: boolean;
432
+ }>;
@@ -1,10 +1,32 @@
1
1
  import { readdirSync, readFileSync, statSync } from "node:fs";
2
2
  import { extname, join, relative } from "node:path";
3
+ /** Public control plane. */
4
+ export const DEFAULT_BASE_URL = "https://api.novence.ai";
3
5
  /**
4
- * Public control plane. Override per-call, or globally with NOVENCE_BASE_URL
5
- * (useful when pointing the SDK at a local API during development).
6
+ * Resolved per call, not snapshotted at import time, so setting
7
+ * NOVENCE_BASE_URL after import still takes effect — and two copies of this
8
+ * module (see `isNovenceClient`) can never disagree on the target.
6
9
  */
7
- export const DEFAULT_BASE_URL = process.env.NOVENCE_BASE_URL?.replace(/\/$/, "") || "https://api.novence.ai";
10
+ function resolveBaseUrl(explicit) {
11
+ const raw = explicit ?? process.env.NOVENCE_BASE_URL ?? DEFAULT_BASE_URL;
12
+ return raw.replace(/\/$/, "");
13
+ }
14
+ /**
15
+ * Brand for cross-copy identity checks.
16
+ *
17
+ * A package shipped as both ESM and CommonJS can be loaded twice in one process
18
+ * (the "dual package hazard"), which yields two distinct `Novence` classes and
19
+ * makes `instanceof` fail across the boundary. `Symbol.for` is registry-global,
20
+ * so this brand is shared by every copy. Prefer `isNovenceClient()` over
21
+ * `instanceof Novence`.
22
+ */
23
+ const CLIENT_BRAND = Symbol.for("novence.sdk.client");
24
+ /** True for a Novence client from any copy of this module. */
25
+ export function isNovenceClient(value) {
26
+ return (typeof value === "object" &&
27
+ value !== null &&
28
+ value[CLIENT_BRAND] === true);
29
+ }
8
30
  const MIME_BY_EXT = {
9
31
  ".html": "text/html; charset=utf-8",
10
32
  ".css": "text/css; charset=utf-8",
@@ -34,7 +56,12 @@ export class Novence {
34
56
  baseUrl;
35
57
  constructor(opts) {
36
58
  this.apiKey = opts.apiKey;
37
- this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
59
+ this.baseUrl = resolveBaseUrl(opts.baseUrl);
60
+ Object.defineProperty(this, CLIENT_BRAND, {
61
+ value: true,
62
+ enumerable: false,
63
+ writable: false,
64
+ });
38
65
  }
39
66
  async request(method, path, body) {
40
67
  const res = await fetch(`${this.baseUrl}${path}`, {
@@ -181,11 +208,31 @@ export class Novence {
181
208
  revokeSession: () => this.request("DELETE", "/v1/account/sessions/current"),
182
209
  };
183
210
  apiKeys = {
184
- revoke: (id) => this.request("DELETE", `/v1/api-keys/${id}`),
211
+ /**
212
+ * List keys on the account. Never includes the key or its hash — match on
213
+ * `keyPrefix`, and check `current` before revoking.
214
+ */
215
+ list: (opts = {}) => {
216
+ const q = new URLSearchParams();
217
+ if (opts.projectId)
218
+ q.set("projectId", opts.projectId);
219
+ if (opts.includeRevoked)
220
+ q.set("includeRevoked", "true");
221
+ const qs = q.toString();
222
+ return this.request("GET", `/v1/api-keys${qs ? `?${qs}` : ""}`);
223
+ },
224
+ /**
225
+ * Revoke a key. Idempotent.
226
+ *
227
+ * Rejects with 409 when `id` is the key this client authenticates with;
228
+ * pass `force` to override, after which recovery needs `reissueApiKey`
229
+ * with an email OTP.
230
+ */
231
+ revoke: (id, opts = {}) => this.request("DELETE", `/v1/api-keys/${id}${opts.force ? "?force=true" : ""}`),
185
232
  };
186
233
  }
187
- export async function bootstrapAccount(email, baseUrl = DEFAULT_BASE_URL) {
188
- const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/bootstrap`, {
234
+ export async function bootstrapAccount(email, baseUrl) {
235
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/bootstrap`, {
189
236
  method: "POST",
190
237
  headers: { "Content-Type": "application/json" },
191
238
  body: JSON.stringify({ email }),
@@ -195,8 +242,8 @@ export async function bootstrapAccount(email, baseUrl = DEFAULT_BASE_URL) {
195
242
  throw new Error(data.error ?? `HTTP ${res.status}`);
196
243
  return data;
197
244
  }
198
- export async function verifyEmail(email, code, baseUrl = DEFAULT_BASE_URL) {
199
- const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/auth/verify-email`, {
245
+ export async function verifyEmail(email, code, baseUrl) {
246
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/verify-email`, {
200
247
  method: "POST",
201
248
  headers: { "Content-Type": "application/json" },
202
249
  body: JSON.stringify({ email, code }),
@@ -206,8 +253,8 @@ export async function verifyEmail(email, code, baseUrl = DEFAULT_BASE_URL) {
206
253
  throw new Error(data.error ?? `HTTP ${res.status}`);
207
254
  return data;
208
255
  }
209
- export async function resendVerification(email, baseUrl = DEFAULT_BASE_URL) {
210
- const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/auth/resend-verification`, {
256
+ export async function resendVerification(email, baseUrl) {
257
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/resend-verification`, {
211
258
  method: "POST",
212
259
  headers: { "Content-Type": "application/json" },
213
260
  body: JSON.stringify({ email }),
@@ -218,8 +265,8 @@ export async function resendVerification(email, baseUrl = DEFAULT_BASE_URL) {
218
265
  return data;
219
266
  }
220
267
  /** Recover a lost account API key with email OTP (after resend-verification). */
221
- export async function reissueApiKey(email, code, baseUrl = DEFAULT_BASE_URL) {
222
- const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/auth/reissue-key`, {
268
+ export async function reissueApiKey(email, code, baseUrl) {
269
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/reissue-key`, {
223
270
  method: "POST",
224
271
  headers: { "Content-Type": "application/json" },
225
272
  body: JSON.stringify({ email, code }),
@@ -0,0 +1,3 @@
1
+ {
2
+ "type": "module"
3
+ }
package/package.json CHANGED
@@ -1,16 +1,19 @@
1
1
  {
2
2
  "name": "@novence/sdk",
3
- "version": "0.1.0",
4
- "description": "Official TypeScript SDK for Novence — static site hosting for AI agents. Create projects, upload files, run quality checks, deploy to the edge.",
3
+ "version": "0.2.1",
4
+ "description": "Official TypeScript SDK for Novence \u2014 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",
7
- "main": "./dist/index.js",
8
- "types": "./dist/index.d.ts",
7
+ "main": "./dist/cjs/index.js",
8
+ "types": "./dist/cjs/index.d.ts",
9
9
  "exports": {
10
10
  ".": {
11
- "types": "./dist/index.d.ts",
12
- "import": "./dist/index.js"
13
- }
11
+ "types": "./dist/esm/index.d.ts",
12
+ "import": "./dist/esm/index.js",
13
+ "require": "./dist/cjs/index.js",
14
+ "default": "./dist/esm/index.js"
15
+ },
16
+ "./package.json": "./package.json"
14
17
  },
15
18
  "files": [
16
19
  "dist",
@@ -40,12 +43,13 @@
40
43
  "access": "public"
41
44
  },
42
45
  "scripts": {
43
- "build": "tsc -p tsconfig.json",
44
- "typecheck": "tsc -p tsconfig.json --noEmit",
46
+ "build": "rm -rf dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/fixup.mjs",
47
+ "typecheck": "tsc -p tsconfig.json",
45
48
  "prepublishOnly": "pnpm run build"
46
49
  },
47
50
  "devDependencies": {
48
51
  "@types/node": "^22.10.2",
49
52
  "typescript": "^5.7.2"
50
- }
53
+ },
54
+ "module": "./dist/esm/index.js"
51
55
  }