@zilfu/sdk 0.0.1 → 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,47 +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, getApiSpaces } from '@zilfu/sdk';
+import { createZilfuClient } from "@zilfu/sdk";
 
-createZilfuClient({
-  baseUrl: 'https://zilfu.com',
+const api = createZilfuClient({
+  baseUrl: "https://zilfu.app/api",
   token: process.env.ZILFU_TOKEN!,
 });
 
-const { data, error } = await getApiSpaces();
-if (error) throw error;
-console.log(data);
+const spaces = await api.spaces.list();
 ```
 
-### Custom fetch (edge runtimes)
+## 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
-createZilfuClient({
-  baseUrl: 'https://zilfu.com',
+const api = createZilfuClient({
+  token: async () => await getTokenFromVault(),
+});
+```
+
+The `Authorization: Bearer <token>` header is added automatically to every request.
+
+## Examples
+
+```ts
+// 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