@novence/sdk 0.2.1 → 0.2.3

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
@@ -2,7 +2,16 @@
2
2
 
3
3
  Official TypeScript SDK for [Novence](https://novence.ai) — static site hosting built for AI agents and the developers who wire them up.
4
4
 
5
- Create a project, upload HTML/CSS/JS, run quality checks, and publish to the edge at `https://{suffix}.novence.ai/`.
5
+ Prefer the CLI for a first publish — no email until you claim:
6
+
7
+ ```bash
8
+ npx novence deploy ./dist
9
+ novence claim --email you@example.com
10
+ ```
11
+
12
+ This SDK is for app and script code **after** you have an `nv_` key. Create a
13
+ project, upload HTML/CSS/JS, run quality checks, and publish to the edge at
14
+ `https://{suffix}.novence.ai/`.
6
15
 
7
16
  ```bash
8
17
  npm install @novence/sdk
@@ -18,6 +27,21 @@ const { Novence } = require("@novence/sdk"); // CommonJS
18
27
 
19
28
  ## Quick start
20
29
 
30
+ ```ts
31
+ import { Novence } from "@novence/sdk";
32
+
33
+ const client = new Novence({ apiKey: process.env.NOVENCE_API_KEY! });
34
+ const { project, url } = await client.projects.create({ name: "launch" });
35
+ await client.files.uploadDir(project.id, "./site");
36
+ await client.deployments.create(project.id);
37
+
38
+ console.log(url); // https://{suffix}.novence.ai
39
+ ```
40
+
41
+ ### Bootstrap + verify (email path)
42
+
43
+ When you need a key from email OTP instead of the CLI:
44
+
21
45
  ```ts
22
46
  import { Novence, bootstrapAccount, verifyEmail } from "@novence/sdk";
23
47
 
@@ -36,6 +60,9 @@ await client.deployments.create(project.id);
36
60
  console.log(url); // https://{suffix}.novence.ai
37
61
  ```
38
62
 
63
+ Or deploy anonymously from the SDK, then claim:
64
+ `createDemoAccount()` → ship → `claimAccount(apiKey, "you@example.com")`.
65
+
39
66
  Deploys are asynchronous. Poll `deployments.latest` until it settles:
40
67
 
41
68
  ```ts
@@ -98,8 +125,8 @@ call at a different control plane — useful when running the API locally.
98
125
  | `client.account` | `get` · `consoleKit` · `createSession` · `revokeSession` |
99
126
  | `client.apiKeys` | `revoke` |
100
127
 
101
- Standalone helpers for the pre-auth flow: `bootstrapAccount`, `verifyEmail`,
102
- `resendVerification`, `reissueApiKey`.
128
+ Standalone helpers for the pre-auth flow: `createDemoAccount`, `claimAccount`,
129
+ `bootstrapAccount`, `verifyEmail`, `resendVerification`, `reissueApiKey`.
103
130
 
104
131
  ## Identity checks
105
132
 
@@ -2,6 +2,14 @@
2
2
  export declare const DEFAULT_BASE_URL = "https://api.novence.ai";
3
3
  /** True for a Novence client from any copy of this module. */
4
4
  export declare function isNovenceClient(value: unknown): value is Novence;
5
+ /**
6
+ * Thrown for any non-2xx API response. `status` lets callers distinguish 401
7
+ * from 402 from 429 without matching on message text.
8
+ */
9
+ export declare class NovenceError extends Error {
10
+ readonly status: number;
11
+ constructor(message: string, status: number);
12
+ }
5
13
  export interface NovenceOptions {
6
14
  apiKey: string;
7
15
  baseUrl?: string;
@@ -413,6 +421,22 @@ export declare function bootstrapAccount(email: string, baseUrl?: string): Promi
413
421
  emailVerificationRequired?: boolean;
414
422
  verificationCode?: string;
415
423
  }>;
424
+ export declare function createDemoAccount(baseUrl?: string): Promise<{
425
+ accountId: string;
426
+ apiKey: string;
427
+ plan: string;
428
+ anonymous: true;
429
+ emailVerificationRequired: true;
430
+ claim: string;
431
+ }>;
432
+ export declare function claimAccount(apiKey: string, email: string, baseUrl?: string): Promise<{
433
+ accountId: string;
434
+ email: string;
435
+ sent?: boolean;
436
+ emailVerificationRequired?: boolean;
437
+ alreadyVerified?: boolean;
438
+ verificationCode?: string;
439
+ }>;
416
440
  export declare function verifyEmail(email: string, code: string, baseUrl?: string): Promise<{
417
441
  accountId: string;
418
442
  emailVerified: boolean;
package/dist/cjs/index.js CHANGED
@@ -1,8 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.Novence = exports.DEFAULT_BASE_URL = void 0;
3
+ exports.Novence = exports.NovenceError = exports.DEFAULT_BASE_URL = void 0;
4
4
  exports.isNovenceClient = isNovenceClient;
5
5
  exports.bootstrapAccount = bootstrapAccount;
6
+ exports.createDemoAccount = createDemoAccount;
7
+ exports.claimAccount = claimAccount;
6
8
  exports.verifyEmail = verifyEmail;
7
9
  exports.resendVerification = resendVerification;
8
10
  exports.reissueApiKey = reissueApiKey;
@@ -35,6 +37,19 @@ function isNovenceClient(value) {
35
37
  value !== null &&
36
38
  value[CLIENT_BRAND] === true);
37
39
  }
40
+ /**
41
+ * Thrown for any non-2xx API response. `status` lets callers distinguish 401
42
+ * from 402 from 429 without matching on message text.
43
+ */
44
+ class NovenceError extends Error {
45
+ status;
46
+ constructor(message, status) {
47
+ super(message);
48
+ this.name = "NovenceError";
49
+ this.status = status;
50
+ }
51
+ }
52
+ exports.NovenceError = NovenceError;
38
53
  const MIME_BY_EXT = {
39
54
  ".html": "text/html; charset=utf-8",
40
55
  ".css": "text/css; charset=utf-8",
@@ -82,7 +97,7 @@ class Novence {
82
97
  });
83
98
  const data = (await res.json());
84
99
  if (!res.ok) {
85
- throw new Error(data.error ?? `HTTP ${res.status}`);
100
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
86
101
  }
87
102
  return data;
88
103
  }
@@ -124,7 +139,7 @@ class Novence {
124
139
  body: new Blob([copy], { type }),
125
140
  });
126
141
  if (!put.ok)
127
- throw new Error(`Upload failed: ${put.status}`);
142
+ throw new NovenceError(`Upload failed for ${path}`, put.status);
128
143
  return this.files.confirm(projectId, path, type);
129
144
  },
130
145
  /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
@@ -248,7 +263,32 @@ async function bootstrapAccount(email, baseUrl) {
248
263
  });
249
264
  const data = (await res.json());
250
265
  if (!res.ok)
251
- throw new Error(data.error ?? `HTTP ${res.status}`);
266
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
267
+ return data;
268
+ }
269
+ async function createDemoAccount(baseUrl) {
270
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/demo`, {
271
+ method: "POST",
272
+ headers: { "Content-Type": "application/json" },
273
+ body: JSON.stringify({}),
274
+ });
275
+ const data = (await res.json());
276
+ if (!res.ok)
277
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
278
+ return data;
279
+ }
280
+ async function claimAccount(apiKey, email, baseUrl) {
281
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/claim`, {
282
+ method: "POST",
283
+ headers: {
284
+ "Content-Type": "application/json",
285
+ Authorization: `Bearer ${apiKey}`,
286
+ },
287
+ body: JSON.stringify({ email }),
288
+ });
289
+ const data = (await res.json());
290
+ if (!res.ok)
291
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
252
292
  return data;
253
293
  }
254
294
  async function verifyEmail(email, code, baseUrl) {
@@ -259,7 +299,7 @@ async function verifyEmail(email, code, baseUrl) {
259
299
  });
260
300
  const data = (await res.json());
261
301
  if (!res.ok)
262
- throw new Error(data.error ?? `HTTP ${res.status}`);
302
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
263
303
  return data;
264
304
  }
265
305
  async function resendVerification(email, baseUrl) {
@@ -270,7 +310,7 @@ async function resendVerification(email, baseUrl) {
270
310
  });
271
311
  const data = (await res.json());
272
312
  if (!res.ok)
273
- throw new Error(data.error ?? `HTTP ${res.status}`);
313
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
274
314
  return data;
275
315
  }
276
316
  /** Recover a lost account API key with email OTP (after resend-verification). */
@@ -282,6 +322,6 @@ async function reissueApiKey(email, code, baseUrl) {
282
322
  });
283
323
  const data = (await res.json());
284
324
  if (!res.ok)
285
- throw new Error(data.error ?? `HTTP ${res.status}`);
325
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
286
326
  return data;
287
327
  }
@@ -2,6 +2,14 @@
2
2
  export declare const DEFAULT_BASE_URL = "https://api.novence.ai";
3
3
  /** True for a Novence client from any copy of this module. */
4
4
  export declare function isNovenceClient(value: unknown): value is Novence;
5
+ /**
6
+ * Thrown for any non-2xx API response. `status` lets callers distinguish 401
7
+ * from 402 from 429 without matching on message text.
8
+ */
9
+ export declare class NovenceError extends Error {
10
+ readonly status: number;
11
+ constructor(message: string, status: number);
12
+ }
5
13
  export interface NovenceOptions {
6
14
  apiKey: string;
7
15
  baseUrl?: string;
@@ -413,6 +421,22 @@ export declare function bootstrapAccount(email: string, baseUrl?: string): Promi
413
421
  emailVerificationRequired?: boolean;
414
422
  verificationCode?: string;
415
423
  }>;
424
+ export declare function createDemoAccount(baseUrl?: string): Promise<{
425
+ accountId: string;
426
+ apiKey: string;
427
+ plan: string;
428
+ anonymous: true;
429
+ emailVerificationRequired: true;
430
+ claim: string;
431
+ }>;
432
+ export declare function claimAccount(apiKey: string, email: string, baseUrl?: string): Promise<{
433
+ accountId: string;
434
+ email: string;
435
+ sent?: boolean;
436
+ emailVerificationRequired?: boolean;
437
+ alreadyVerified?: boolean;
438
+ verificationCode?: string;
439
+ }>;
416
440
  export declare function verifyEmail(email: string, code: string, baseUrl?: string): Promise<{
417
441
  accountId: string;
418
442
  emailVerified: boolean;
package/dist/esm/index.js CHANGED
@@ -27,6 +27,18 @@ export function isNovenceClient(value) {
27
27
  value !== null &&
28
28
  value[CLIENT_BRAND] === true);
29
29
  }
30
+ /**
31
+ * Thrown for any non-2xx API response. `status` lets callers distinguish 401
32
+ * from 402 from 429 without matching on message text.
33
+ */
34
+ export class NovenceError extends Error {
35
+ status;
36
+ constructor(message, status) {
37
+ super(message);
38
+ this.name = "NovenceError";
39
+ this.status = status;
40
+ }
41
+ }
30
42
  const MIME_BY_EXT = {
31
43
  ".html": "text/html; charset=utf-8",
32
44
  ".css": "text/css; charset=utf-8",
@@ -74,7 +86,7 @@ export class Novence {
74
86
  });
75
87
  const data = (await res.json());
76
88
  if (!res.ok) {
77
- throw new Error(data.error ?? `HTTP ${res.status}`);
89
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
78
90
  }
79
91
  return data;
80
92
  }
@@ -116,7 +128,7 @@ export class Novence {
116
128
  body: new Blob([copy], { type }),
117
129
  });
118
130
  if (!put.ok)
119
- throw new Error(`Upload failed: ${put.status}`);
131
+ throw new NovenceError(`Upload failed for ${path}`, put.status);
120
132
  return this.files.confirm(projectId, path, type);
121
133
  },
122
134
  /** Node-only: upload every allowed file under `dir` with root-relative site paths. */
@@ -239,7 +251,32 @@ export async function bootstrapAccount(email, baseUrl) {
239
251
  });
240
252
  const data = (await res.json());
241
253
  if (!res.ok)
242
- throw new Error(data.error ?? `HTTP ${res.status}`);
254
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
255
+ return data;
256
+ }
257
+ export async function createDemoAccount(baseUrl) {
258
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/demo`, {
259
+ method: "POST",
260
+ headers: { "Content-Type": "application/json" },
261
+ body: JSON.stringify({}),
262
+ });
263
+ const data = (await res.json());
264
+ if (!res.ok)
265
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
266
+ return data;
267
+ }
268
+ export async function claimAccount(apiKey, email, baseUrl) {
269
+ const res = await fetch(`${resolveBaseUrl(baseUrl)}/v1/auth/claim`, {
270
+ method: "POST",
271
+ headers: {
272
+ "Content-Type": "application/json",
273
+ Authorization: `Bearer ${apiKey}`,
274
+ },
275
+ body: JSON.stringify({ email }),
276
+ });
277
+ const data = (await res.json());
278
+ if (!res.ok)
279
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
243
280
  return data;
244
281
  }
245
282
  export async function verifyEmail(email, code, baseUrl) {
@@ -250,7 +287,7 @@ export async function verifyEmail(email, code, baseUrl) {
250
287
  });
251
288
  const data = (await res.json());
252
289
  if (!res.ok)
253
- throw new Error(data.error ?? `HTTP ${res.status}`);
290
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
254
291
  return data;
255
292
  }
256
293
  export async function resendVerification(email, baseUrl) {
@@ -261,7 +298,7 @@ export async function resendVerification(email, baseUrl) {
261
298
  });
262
299
  const data = (await res.json());
263
300
  if (!res.ok)
264
- throw new Error(data.error ?? `HTTP ${res.status}`);
301
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
265
302
  return data;
266
303
  }
267
304
  /** Recover a lost account API key with email OTP (after resend-verification). */
@@ -273,6 +310,6 @@ export async function reissueApiKey(email, code, baseUrl) {
273
310
  });
274
311
  const data = (await res.json());
275
312
  if (!res.ok)
276
- throw new Error(data.error ?? `HTTP ${res.status}`);
313
+ throw new NovenceError(data.error ?? `HTTP ${res.status}`, res.status);
277
314
  return data;
278
315
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@novence/sdk",
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.",
3
+ "version": "0.2.3",
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",
7
7
  "main": "./dist/cjs/index.js",
@@ -36,20 +36,24 @@
36
36
  "edge",
37
37
  "mcp",
38
38
  "ai-agents",
39
+ "claude",
40
+ "cursor",
41
+ "mcp-server",
42
+ "static-hosting",
43
+ "netlify-alternative",
39
44
  "lighthouse",
40
45
  "axe"
41
46
  ],
42
47
  "publishConfig": {
43
48
  "access": "public"
44
49
  },
45
- "scripts": {
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",
48
- "prepublishOnly": "pnpm run build"
49
- },
50
50
  "devDependencies": {
51
51
  "@types/node": "^22.10.2",
52
52
  "typescript": "^5.7.2"
53
53
  },
54
- "module": "./dist/esm/index.js"
55
- }
54
+ "module": "./dist/esm/index.js",
55
+ "scripts": {
56
+ "build": "rm -rf dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/fixup.mjs",
57
+ "typecheck": "tsc -p tsconfig.json"
58
+ }
59
+ }