@lazrus/nukle 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @lazrus/nukle
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript client for Nukle. Read website content, access media
+metadata, manage input-form schemas from your server, and accept browser-safe
+form submissions.
+
+[Documentation](https://docs.nukle.in) · [API reference](https://docs.nukle.in)
+
+## Install
+
+```sh
+npm install @lazrus/nukle
+```
+
+```sh
+pnpm add @lazrus/nukle
+```
+
+## Quick start
+
+Create a website-scoped API key in Nukle Studio, then use it only on your
+server. Never expose a `nukle_live_...` key in browser code.
+
+```ts
+import { createNukleClient } from "@lazrus/nukle";
+
+const nukle = createNukleClient({ apiKey: process.env.NUKLE_API_KEY! });
+
+const hero = await nukle.getSingleton<{ title: string; subtitle: string }>(
+  "hero",
+);
+const cards = await nukle.getRepeatable<{ title: string }>("cards");
+```
+
+The client uses `https://api.nukle.in` by default. For local development,
+provide your Core origin without `/v1`:
+
+```ts
+const nukle = createNukleClient({
+  apiKey: process.env.NUKLE_API_KEY!,
+  baseUrl: "http://localhost:3001",
+});
+```
+
+## What you can do
+
+- Read all modules, a single module, singleton content, or repeatable content.
+- List media, retrieve media metadata, and download authenticated media bytes.
+- Create, inspect, activate, deactivate, and rotate public credentials for
+  input forms from server-only code.
+- Submit a public form from a browser using its restricted `nukle_form_...`
+  credential.
+
+```ts
+import { createNukleFormClient } from "@lazrus/nukle";
+
+const contact = createNukleFormClient({
+  formKey: "nukle_form_REPLACE_ME",
+});
+
+await contact.submit({
+  email: "reader@example.com",
+  message: "Hello from our website",
+});
+```
+
+The form credential is safe for browser code. It cannot access website
+content, media, or form-management operations. Configure the form's allowed
+origins in Nukle before accepting browser submissions.
+
+## Errors
+
+API failures are thrown as `NukleApiError`, with an HTTP `status`, stable
+`code`, and optional `details` field.
+
+```ts
+import { NukleApiError } from "@lazrus/nukle";
+
+try {
+  await nukle.getModule("hero");
+} catch (error) {
+  if (error instanceof NukleApiError) {
+    console.error(error.status, error.code, error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Documentation
+
+Visit [docs.nukle.in](https://docs.nukle.in) for the complete API reference,
+form-management guide, local-development setup, and runnable examples.

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+export type ContentEntry<T = Record<string, unknown>> = {
+    id: string;
+    data: T;
+    position: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type PublicModule<T = Record<string, unknown>> = {
+    key: string;
+    name: string;
+    kind: "singleton" | "repeatable";
+    position: number;
+    entries: ContentEntry<T>[];
+};
+export type PublicMedia = {
+    id: string;
+    websiteId: string | null;
+    originalName: string;
+    mimeType: string;
+    sizeBytes: number;
+    altText: string | null;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type NukleClientOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+export declare class NukleApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined);
+}
+export declare function createNukleClient(options: NukleClientOptions): {
+    getModules: () => Promise<PublicModule<Record<string, unknown>>[]>;
+    getModule: <T = Record<string, unknown>>(moduleKey: string) => Promise<PublicModule<T>>;
+    getSingleton<T = Record<string, unknown>>(moduleKey: string): Promise<NonNullable<T> | null>;
+    getRepeatable<T = Record<string, unknown>>(moduleKey: string): Promise<T[]>;
+    listMedia: () => Promise<PublicMedia[]>;
+    getMedia: (mediaId: string) => Promise<PublicMedia>;
+    getMediaFile: (mediaId: string) => Promise<ArrayBuffer>;
+};
+export type NukleClient = ReturnType<typeof createNukleClient>;
+export type InputFormField = {
+    key: string;
+    label: string;
+    type: "text" | "email" | "tel" | "textarea" | "checkbox" | "select";
+    required?: boolean;
+    maxLength?: number;
+    options?: string[];
+};
+export type InputFormSchema = {
+    name: string;
+    allowedOrigins: string[];
+    fields: InputFormField[];
+};
+export type InputForm = InputFormSchema & {
+    id: string;
+    websiteId: string;
+    key: string;
+    schemaVersion: number;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+export type InputFormWithPublicKey = InputForm & {
+    publicKey: string;
+};
+export type InputFormUpsertResult = InputForm & {
+    publicKey?: string;
+};
+export type NukleFormManagementClientOptions = {
+    apiKey: string;
+    websiteId: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+export type NukleFormClientOptions = {
+    formKey: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * Manages a single website's input-form schemas. Keep this client and its
+ * `nukle_live_...` API key in server-only code.
+ */
+export declare function createNukleFormManagementClient(options: NukleFormManagementClientOptions): {
+    upsert: (formKey: string, schema: InputFormSchema) => Promise<InputFormUpsertResult>;
+    get: (formKey: string) => Promise<InputForm>;
+    rotatePublicKey: (formKey: string) => Promise<InputFormWithPublicKey>;
+    setActive: (formKey: string, active: boolean) => Promise<InputForm>;
+};
+/**
+ * Submits data to exactly one public input form. It is safe to use in browser
+ * code because a `nukle_form_...` key cannot read content or manage schemas.
+ */
+export declare function createNukleFormClient(options: NukleFormClientOptions): {
+    submit(data: Record<string, unknown>): Promise<{
+        ok: boolean;
+        submissionId?: string;
+    }>;
+};
+export type NukleFormManagementClient = ReturnType<typeof createNukleFormManagementClient>;
+export type NukleFormClient = ReturnType<typeof createNukleFormClient>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,155 @@
+export class NukleApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "NukleApiError";
+    }
+}
+const DEFAULT_BASE_URL = "https://api.nukle.in";
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+export function createNukleClient(options) {
+    if (!options.apiKey.trim())
+        throw new Error("Nukle API key is required.");
+    const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    const requestFetch = options.fetch ?? globalThis.fetch;
+    if (!requestFetch)
+        throw new Error("A fetch implementation is required.");
+    async function request(path, init) {
+        const response = await requestFetch(`${baseUrl}/v1${path}`, {
+            ...init,
+            headers: {
+                Accept: "application/json",
+                ...init?.headers,
+                "x-nukle-api-key": options.apiKey,
+            },
+        });
+        if (!response.ok) {
+            let payload = {};
+            try {
+                payload = (await response.json());
+            }
+            catch {
+                // Preserve the HTTP status when the server returns a non-JSON error.
+            }
+            throw new NukleApiError(response.status, payload.error?.code ?? "NUKLE_REQUEST_FAILED", payload.error?.message ?? `Nukle request failed (${response.status}).`, payload.error?.details);
+        }
+        return (await response.json());
+    }
+    async function getModule(moduleKey) {
+        return request(`/public/modules/${encodeURIComponent(moduleKey)}`);
+    }
+    return {
+        getModules: () => request("/public/modules"),
+        getModule,
+        async getSingleton(moduleKey) {
+            const module = await getModule(moduleKey);
+            return module.entries[0]?.data ?? null;
+        },
+        async getRepeatable(moduleKey) {
+            const module = await getModule(moduleKey);
+            return module.entries.map((entry) => entry.data);
+        },
+        listMedia: () => request("/public/media"),
+        getMedia: (mediaId) => request(`/public/media/${encodeURIComponent(mediaId)}`),
+        getMediaFile: async (mediaId) => {
+            const response = await requestFetch(`${baseUrl}/v1/public/media/${encodeURIComponent(mediaId)}/file`, {
+                headers: { "x-nukle-api-key": options.apiKey },
+            });
+            if (!response.ok) {
+                let payload = {};
+                try {
+                    payload = (await response.json());
+                }
+                catch {
+                    // Preserve the HTTP status when the server returns a non-JSON error.
+                }
+                throw new NukleApiError(response.status, payload.error?.code ?? "NUKLE_REQUEST_FAILED", payload.error?.message ??
+                    `Nukle request failed (${response.status}).`, payload.error?.details);
+            }
+            return response.arrayBuffer();
+        },
+    };
+}
+function createJsonRequest(baseUrl, requestFetch, path, init) {
+    return requestFetch(`${baseUrl}/v1${path}`, {
+        ...init,
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            ...init.headers,
+        },
+    });
+}
+async function readJson(response) {
+    if (response.ok)
+        return (await response.json());
+    let payload = {};
+    try {
+        payload = (await response.json());
+    }
+    catch {
+        // Preserve the HTTP status when the server returns a non-JSON error.
+    }
+    throw new NukleApiError(response.status, payload.error?.code ?? "NUKLE_REQUEST_FAILED", payload.error?.message ?? `Nukle request failed (${response.status}).`, payload.error?.details);
+}
+/**
+ * Manages a single website's input-form schemas. Keep this client and its
+ * `nukle_live_...` API key in server-only code.
+ */
+export function createNukleFormManagementClient(options) {
+    if (!options.apiKey.trim())
+        throw new Error("Nukle API key is required.");
+    if (!options.websiteId.trim())
+        throw new Error("Nukle website ID is required.");
+    const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    const requestFetch = options.fetch ?? globalThis.fetch;
+    if (!requestFetch)
+        throw new Error("A fetch implementation is required.");
+    const formsPath = `/websites/${encodeURIComponent(options.websiteId)}/forms`;
+    function request(path, init) {
+        return createJsonRequest(baseUrl, requestFetch, path, {
+            ...init,
+            headers: { ...init.headers, "x-nukle-api-key": options.apiKey },
+        }).then((readJson));
+    }
+    return {
+        upsert: (formKey, schema) => request(`${formsPath}/${encodeURIComponent(formKey)}`, { method: "PUT", body: JSON.stringify(schema) }),
+        get: (formKey) => request(`${formsPath}/${encodeURIComponent(formKey)}`, {
+            method: "GET",
+        }),
+        rotatePublicKey: (formKey) => request(`${formsPath}/${encodeURIComponent(formKey)}/rotate-key`, { method: "POST" }),
+        setActive: (formKey, active) => request(`${formsPath}/${encodeURIComponent(formKey)}`, {
+            method: "PATCH",
+            body: JSON.stringify({ active }),
+        }),
+    };
+}
+/**
+ * Submits data to exactly one public input form. It is safe to use in browser
+ * code because a `nukle_form_...` key cannot read content or manage schemas.
+ */
+export function createNukleFormClient(options) {
+    if (!options.formKey.trim())
+        throw new Error("Nukle form key is required.");
+    const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    const requestFetch = options.fetch ?? globalThis.fetch;
+    if (!requestFetch)
+        throw new Error("A fetch implementation is required.");
+    return {
+        async submit(data) {
+            const response = await createJsonRequest(baseUrl, requestFetch, `/public/forms/${encodeURIComponent(options.formKey)}/submissions`, {
+                method: "POST",
+                headers: { "x-nukle-form-key": options.formKey },
+                body: JSON.stringify({ data, website: "" }),
+            });
+            return readJson(response);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@lazrus/nukle",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "Typed client for Nukle public website delivery APIs.",
+  "homepage": "https://docs.nukle.in",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "eslint": "^9",
+    "tsx": "^4.23.15",
+    "typescript": "5.9.2",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check-types": "tsc --noEmit",
+    "test": "tsx --test src/**/*.test.ts",
+    "lint": "eslint . --max-warnings 0"
+  }
 }