@zilfu/sdk 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zilfu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,51 +1,143 @@
 # @zilfu/sdk
 
-Official TypeScript SDK for the [Zilfu](https://zilfu.com) API. Type-safe client generated from the live OpenAPI spec — works in browser, Node 18+, and edge runtimes (Cloudflare Workers, Vercel Edge).
+Official TypeScript SDK for the [Zilfu](https://zilfu.app) API.
 
 ## Install
 
-```bash
+```sh
 pnpm add @zilfu/sdk
 # or
 npm install @zilfu/sdk
 ```
 
-## Usage
+Requires Node 18.17+ (or any runtime with global `fetch`).
 
-Get a personal access token from your Zilfu account settings, then:
+## Quickstart
 
 ```ts
-import { createZilfuClient } from '@zilfu/sdk';
+import { createZilfuClient } from "@zilfu/sdk";
 
 const api = createZilfuClient({
-  baseUrl: 'https://zilfu.com/api',
+  baseUrl: "https://zilfu.app/api",
   token: process.env.ZILFU_TOKEN!,
 });
 
-const { data: spaces } = await api.spaces.list();
-const { data: post } = await api.posts.create({
-  path: { space: '1' },
-  body: { space_id: 1, items: [{ account_id: 1, social: 'threads', main: { content: 'hi' } }] },
+const spaces = await api.spaces.list();
+```
+
+## Auth
+
+Mint a personal-access token at **Settings → API tokens** (or via `POST /api/api-tokens`). Pass it as a string or as a function for refresh logic:
+
+```ts
+const api = createZilfuClient({
+  token: async () => await getTokenFromVault(),
 });
 ```
 
-Available namespaces: `accounts`, `bio`, `bioBlocks`, `clusters`, `media`, `posts`, `queue`, `slots`, `spaces`, `subscription`, `tokens`, `webhooks`. Each exposes typed `list / get / create / update / delete` plus resource-specific verbs (`activate`, `boards`, `reorder`, `uploadAvatar`, etc.).
+The `Authorization: Bearer <token>` header is added automatically to every request.
 
-### Custom fetch (edge runtimes)
+## Examples
 
 ```ts
-createZilfuClient({
-  baseUrl: 'https://zilfu.com',
+// List posts in a space
+await api.posts.list({ path: { space: 1 } });
+
+// Create a multi-account post (a "cluster")
+await api.posts.create({
+  path: { space: 1 },
+  body: {
+    space_id: 1,
+    items: [{ account_id: 1, social: "threads", main: { content: "Hello" } }],
+  },
+});
+
+// Update an entire cluster
+await api.clusters.update({
+  path: { space: 1, cluster_id: "abc-123" },
+  body: { /* same shape as create */ },
+});
+
+// Reorder a bio link block
+await api.bio.blocks.reorder({
+  path: { space: 1, block: 7 },
+  body: { sort_order: 2 },
+});
+
+// Upload media (FormData)
+const fd = new FormData();
+fd.append("file", file);
+await api.media.create({ body: fd });
+```
+
+## Errors
+
+Non-2xx responses throw a typed `ZilfuApiError`:
+
+```ts
+import { ZilfuApiError } from "@zilfu/sdk";
+
+try {
+  await api.posts.create({ /* ... */ });
+} catch (e) {
+  if (e instanceof ZilfuApiError) {
+    console.error(e.status, e.errors); // Laravel validation: { field: ["msg"] }
+  }
+}
+```
+
+## Types
+
+```ts
+import type {
+  PostResource,
+  SpaceResource,
+  AccountResource,
+  WebhookResource,
+} from "@zilfu/sdk";
+```
+
+All request/response shapes are exported as named types.
+
+## Custom fetch
+
+```ts
+import { fetch as undiciFetch } from "undici";
+
+const api = createZilfuClient({
   token,
-  fetch: globalThis.fetch.bind(globalThis),
+  fetch: undiciFetch,
 });
 ```
 
-## Development
+## Regenerating from the API spec
+
+The package is generated from the live OpenAPI spec at `https://zilfu.app/docs/api.json` (Scramble).
+
+```sh
+pnpm sync:spec     # fetches openapi.json
+pnpm generate      # regenerates src/generated
+pnpm typecheck     # verifies the smoke file still compiles
+pnpm build
+```
+
+Override the spec source for staging or local Herd:
+
+```sh
+SCRAMBLE_SPEC_URL=http://zilfu.test/docs/api.json pnpm sync:spec
+```
+
+The generated `src/generated/` directory is committed; PRs that bump the spec show a reviewable diff of API surface changes.
+
+A daily GitHub Actions cron (`.github/workflows/sync-spec.yml`) does this automatically and opens a PR if anything changed — review and merge, then cut a release with:
 
-```bash
-pnpm sync       # export openapi.json from the Laravel app
-pnpm generate   # regenerate src/generated/ from openapi.json
-pnpm build      # bundle dist/
-pnpm typecheck
+```sh
+pnpm version <patch|minor|major>
+git push --follow-tags
 ```
+
+The release workflow (`.github/workflows/release.yml`) publishes to npm with provenance and creates a GitHub release on every `v*` tag.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -823,7 +823,7 @@ var HeyApiRegistry = class {
   get(key) {
     const instance = this.instances.get(key ?? this.defaultKey);
     if (!instance) {
-      throw new Error(`No SDK client found. Create one with "new ZilfuClient()" to fix this error.`);
+      throw new Error(`No SDK client found. Create one with "new ZilfuApi()" to fix this error.`);
     }
     return instance;
   }
@@ -893,7 +893,7 @@ var Accounts = class extends HeyApiClient {
     });
   }
 };
-var Tokens = class extends HeyApiClient {
+var ApiTokens = class extends HeyApiClient {
   /**
    * Create an API token
    *
@@ -923,7 +923,7 @@ var Tokens = class extends HeyApiClient {
     });
   }
 };
-var BioBlocks = class extends HeyApiClient {
+var Blocks = class extends HeyApiClient {
   list(options) {
     return (options.client ?? this.client).get({
       security: [{ scheme: "bearer", type: "http" }],
@@ -1014,6 +1014,19 @@ var Bio = class extends HeyApiClient {
       }
     });
   }
+  _blocks;
+  get blocks() {
+    return this._blocks ??= new Blocks({ client: this.client });
+  }
+};
+var Health = class extends HeyApiClient {
+  check(options) {
+    return (options?.client ?? this.client).get({
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/health",
+      ...options
+    });
+  }
 };
 var Media = class extends HeyApiClient {
   /**
@@ -1332,28 +1345,28 @@ var Webhooks = class extends HeyApiClient {
     });
   }
 };
-var ZilfuClient = class _ZilfuClient extends HeyApiClient {
+var ZilfuApi = class _ZilfuApi extends HeyApiClient {
   static __registry = new HeyApiRegistry();
   constructor(args) {
     super(args);
-    _ZilfuClient.__registry.set(this, args?.key);
+    _ZilfuApi.__registry.set(this, args?.key);
   }
   _accounts;
   get accounts() {
     return this._accounts ??= new Accounts({ client: this.client });
   }
-  _tokens;
-  get tokens() {
-    return this._tokens ??= new Tokens({ client: this.client });
-  }
-  _bioBlocks;
-  get bioBlocks() {
-    return this._bioBlocks ??= new BioBlocks({ client: this.client });
+  _apiTokens;
+  get apiTokens() {
+    return this._apiTokens ??= new ApiTokens({ client: this.client });
   }
   _bio;
   get bio() {
     return this._bio ??= new Bio({ client: this.client });
   }
+  _health;
+  get health() {
+    return this._health ??= new Health({ client: this.client });
+  }
   _media;
   get media() {
     return this._media ??= new Media({ client: this.client });
@@ -1388,31 +1401,68 @@ var ZilfuClient = class _ZilfuClient extends HeyApiClient {
   }
 };
 
+// src/errors.ts
+var ZilfuApiError = class extends Error {
+  status;
+  statusText;
+  url;
+  body;
+  errors;
+  constructor(init) {
+    const message = extractMessage(init);
+    super(message);
+    this.name = "ZilfuApiError";
+    this.status = init.status;
+    this.statusText = init.statusText;
+    this.url = init.url;
+    this.body = init.body;
+    this.errors = extractValidationErrors(init.body);
+  }
+};
+function extractMessage(init) {
+  const body = init.body;
+  if (body && typeof body === "object" && "message" in body) {
+    const m = body.message;
+    if (typeof m === "string" && m.length > 0) {
+      return m;
+    }
+  }
+  return `Zilfu API ${init.status}${init.statusText ? ` ${init.statusText}` : ""}`;
+}
+function extractValidationErrors(body) {
+  if (!body || typeof body !== "object" || !("errors" in body)) {
+    return void 0;
+  }
+  const errors = body.errors;
+  if (!errors || typeof errors !== "object") {
+    return void 0;
+  }
+  return errors;
+}
+
 // src/client.ts
-function createZilfuClient(options) {
-  const { baseUrl, token, fetch: fetchImpl } = options;
-  client.setConfig({
-    baseUrl,
-    auth: token,
-    ...fetchImpl ? { fetch: fetchImpl } : {}
+function createZilfuClient(opts) {
+  const client2 = createClient(
+    createConfig({
+      baseUrl: opts.baseUrl ?? "https://zilfu.app/api",
+      fetch: opts.fetch,
+      headers: { accept: "application/json", ...opts.headers },
+      auth: opts.token,
+      throwOnError: true
+    })
+  );
+  client2.interceptors.error.use((error, response) => {
+    return new ZilfuApiError({
+      status: response?.status ?? 0,
+      statusText: response?.statusText,
+      url: response?.url,
+      body: error
+    });
   });
-  return new ZilfuClient();
+  return new ZilfuApi({ client: client2 });
 }
 
-exports.Accounts = Accounts;
-exports.Bio = Bio;
-exports.BioBlocks = BioBlocks;
-exports.Clusters = Clusters;
-exports.Media = Media;
-exports.Posts = Posts;
-exports.Queue = Queue;
-exports.Slots = Slots;
-exports.Spaces = Spaces;
-exports.Subscription = Subscription;
-exports.Tokens = Tokens;
-exports.Webhooks = Webhooks;
-exports.ZilfuClient = ZilfuClient;
-exports.client = client;
+exports.ZilfuApiError = ZilfuApiError;
 exports.createZilfuClient = createZilfuClient;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map