@lazrus/nukle 0.2.0 → 0.2.1

package/README.md

@@ -1,21 +1,93 @@
 # @lazrus/nukle
 
-Typed ESM client for Nukle website content, media, and input forms.
+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";
 
-// Server-only: keep the website API key out of browser code.
 const nukle = createNukleClient({ apiKey: process.env.NUKLE_API_KEY! });
-const modules = await nukle.getModules();
+
+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",
+});
 ```
 
-The browser-safe form client uses a separate `nukle_form_...` public credential.
+## What you can do
 
-In the source repository:
+- 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;
+  }
+}
+```
 
-- [Developer reference](../../docs/sdk/README.md)
-- [Development, testing, and npm publishing](../../docs/sdk/development-and-publishing.md)
-- [Runnable examples](../../docs/sdk/examples/README.md)
+## Documentation
 
-The full guides and examples live in the repository and are not included in the npm tarball. This README's relative links are for source checkouts; use the repository documentation when reading a downloaded package. Build with `pnpm --filter @lazrus/nukle build` from the monorepo root.
+Visit [docs.nukle.in](https://docs.nukle.in) for the complete API reference,
+form-management guide, local-development setup, and runnable examples.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@lazrus/nukle",
-  "version": "0.2.0",
+  "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",
@@ -20,8 +21,8 @@
     "eslint": "^9",
     "tsx": "^4.23.15",
     "typescript": "5.9.2",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/eslint-config": "0.0.0"
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
     "build": "tsc",