inkwire-client 0.2.0 → 1.0.0

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
@@ -1,18 +1,62 @@
1
1
  # inkwire-client
2
2
 
3
- Node client for publishing posts to an [Inkwire](https://github.com/etugrand/inkwire) receiver.
3
+ Node client for an [Inkwire](https://github.com/dahoai/inkwire) receiver: publish, read, edit, delete, browse tags and categories, and manage the media library. Zero dependencies (Node 18+: global `fetch`, `FormData`, `Blob`).
4
4
 
5
5
  ```js
6
- import { publish } from "inkwire-client";
6
+ import {
7
+ publish, capabilities, list, get, update, remove, terms, uploadMedia, listMedia, updateMedia, edits, isScheduled,
8
+ } from "inkwire-client";
7
9
 
8
- const result = await publish("https://blog.example.com", "your-api-key", {
9
- external_id: "my-post-1",
10
- title: "Hello",
11
- markdown: "# Hello\n\nFirst post via Inkwire.",
12
- status: "published",
10
+ const site = "https://blog.example.com", key = "your-api-key";
11
+
12
+ await publish(site, key, {
13
+ external_id: "my-post-1", title: "Hello", markdown: "# Hello", status: "published",
14
+ tags: ["seo"], categories: ["Guides"], cover_image_url: "https://…/c.jpg", cover_image_alt: "A red bicycle",
15
+ seo: { og_title: "Social card title", og_description: "Social card text", json_ld: JSON.stringify({ "@context": "https://schema.org", "@type": "FAQPage" }) },
13
16
  });
17
+
18
+ const caps = await capabilities(site, key); // { features, kinds, limits, site? }; a receiver without discovery (404) reads as upsert-only
19
+ if (caps.features.includes("terms")) await terms(site, key, { kind: "category", search: "gui", limit: 20 }); // { items: [{ kind, name, slug, count }] }
20
+ const page = await list(site, key, { status: "published", category: "Guides", search: "hello", limit: 20 }); // { items, next_cursor }
21
+ const next = await list(site, key, { cursor: page.next_cursor });
22
+
23
+ // Safe edit: read, change the exact passage, write back only if nobody changed it meanwhile.
24
+ const { content, etag } = await get(site, key, page.items[0].id);
25
+ const markdown = edits(content.markdown, [{ find: "Hello", replace: "Hello, world" }]);
26
+ await update(site, key, content.id, { markdown }, { ifMatch: etag }); // 412 -> InkwireClientError code "stale"
27
+
28
+ await update(site, key, content.id, { excerpt: null, categories: null, cover_image_alt: null, seo: { noindex: true, json_ld: null } }); // null clears; seo merges per key
29
+ await remove(site, key, content.id);
30
+
31
+ isScheduled(content); // true when status is "published" and published_at is in the future (needs the receiver's `schedule` feature to be held back)
32
+
33
+ const m = await uploadMedia(site, key, { filename: "pic.png", data: bytes, contentType: "image/png", alt: "A picture" });
34
+ // or have the receiver fetch it: uploadMedia(site, key, { url: "https://…/pic.png", alt: "A picture" })
35
+ // m: { id, url, alt?, title?, mime_type, created_at }
36
+
37
+ const library = await listMedia(site, key, { search: "pic", limit: 20 }); // { items: MediaItem[], next_cursor }
38
+ await updateMedia(site, key, m.id, { alt: "A better description", title: null }); // null clears; returns the MediaItem
14
39
  ```
15
40
 
16
- `publish(baseUrl, apiKey, payload, opts?)` upserts by `external_id`, retries on `429`/5xx with backoff, and throws `InkwireClientError` (`code`, `message`, `httpStatus`) on failure.
41
+ Features a receiver can advertise in `capabilities().features`: `upsert` (always), `list`, `get`, `update`, `delete`, `terms`, `schedule`, `media`, `media_list`, `media_update`. Call only what it lists.
42
+
43
+ | Function | Endpoint |
44
+ | --- | --- |
45
+ | `publish(baseUrl, apiKey, payload, opts?)` | `POST /api/content` (upsert on `external_id` + `kind`) |
46
+ | `capabilities(baseUrl, apiKey, opts?)` | `GET /api/inkwire` |
47
+ | `list(baseUrl, apiKey, query?, opts?)` | `GET /api/content` |
48
+ | `get(baseUrl, apiKey, id, opts?)` | `GET /api/content/{id}` -> `{ content, etag }` |
49
+ | `update(baseUrl, apiKey, id, patch, opts?)` | `PATCH /api/content/{id}` -> `{ content, etag }` |
50
+ | `remove(baseUrl, apiKey, id, opts?)` | `DELETE /api/content/{id}` |
51
+ | `terms(baseUrl, apiKey, query?, opts?)` | `GET /api/terms` -> `{ items: { kind, name, slug, count }[] }` |
52
+ | `uploadMedia(baseUrl, apiKey, media, opts?)` | `POST /api/media` -> `MediaItem` |
53
+ | `listMedia(baseUrl, apiKey, query?, opts?)` | `GET /api/media` -> `{ items, next_cursor }` |
54
+ | `updateMedia(baseUrl, apiKey, id, patch, opts?)` | `PATCH /api/media/{id}` -> `MediaItem` |
55
+ | `edits(markdown, changes)` | none: each `find` must match exactly once |
56
+ | `isScheduled(entry, now?)` | none: published with a future `published_at` |
57
+
58
+ Options: `opts.retries` (attempts, default 3; only `429` and `5xx` are retried, with backoff) and `opts.fetch` (send through your own fetch, for example an SSRF-guarded one when the site URL comes from your users). `update` and `remove` also take `opts.ifMatch`.
59
+
60
+ Failures throw `InkwireClientError` with `code` (the protocol's code: `invalid_payload`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `stale`, `too_large`, `rate_limited`, `internal`; `edit_not_found` / `edit_ambiguous` from `edits`), `message` and `httpStatus` (`0` for `edits`).
17
61
 
18
- See the [protocol spec](https://github.com/etugrand/inkwire/blob/master/inkwire/SPEC.md) for the full payload shape.
62
+ Ids (entries and media) are URL-encoded for you. Entry ids are the receiver's: keep the `id` you get back from `publish`/`list` (a kind or slug change can change it on file-backed receivers). See the [protocol spec](https://github.com/dahoai/inkwire/blob/master/inkwire/SPEC.md).
package/dist/index.d.ts CHANGED
@@ -34,6 +34,12 @@ export declare class InkwireClientError extends Error {
34
34
  httpStatus: number;
35
35
  constructor(code: string, message: string, httpStatus: number);
36
36
  }
37
- export declare function publish(baseUrl: string, apiKey: string, payload: PostPayload, opts?: {
37
+ export interface PublishOptions {
38
38
  retries?: number;
39
- }): Promise<PublishResult>;
39
+ /**
40
+ * The fetch to send with (default: global fetch). A server that publishes to user-supplied
41
+ * site URLs should pass an SSRF-guarded fetch that refuses internal hosts on every redirect hop.
42
+ */
43
+ fetch?: (url: string, init: RequestInit) => Promise<Response>;
44
+ }
45
+ export declare function publish(baseUrl: string, apiKey: string, payload: PostPayload, opts?: PublishOptions): Promise<PublishResult>;
package/dist/index.js CHANGED
@@ -10,10 +10,11 @@ export class InkwireClientError extends Error {
10
10
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
11
11
  export async function publish(baseUrl, apiKey, payload, opts = {}) {
12
12
  const retries = Math.max(1, opts.retries ?? 3);
13
+ const send = opts.fetch ?? fetch;
13
14
  const url = `${baseUrl.replace(/\/$/, "")}/api/posts`;
14
15
  let lastErr;
15
16
  for (let attempt = 1; attempt <= retries; attempt++) {
16
- const res = await fetch(url, {
17
+ const res = await send(url, {
17
18
  method: "POST",
18
19
  headers: {
19
20
  "content-type": "application/json",
package/package.json CHANGED
@@ -1,10 +1,27 @@
1
1
  {
2
- "name": "inkwire-client", "version": "0.2.0", "type": "module",
3
- "description": "Client SDK for publishing posts to an Inkwire receiver (idempotent, retrying, typed errors).",
2
+ "name": "inkwire-client",
3
+ "version": "1.0.0",
4
+ "type": "module",
5
+ "description": "Client SDK for an Inkwire receiver: publish, read, edit, delete and upload media, list terms and the media library (idempotent, retrying, typed errors).",
4
6
  "license": "MIT",
5
- "repository": { "type": "git", "url": "https://github.com/etugrand/inkwire.git", "directory": "inkwire/clients/node" },
6
- "main": "dist/index.js", "types": "dist/index.d.ts",
7
- "files": ["dist/*.js", "dist/*.d.ts"],
8
- "scripts": { "build": "tsc", "test": "vitest run" },
9
- "devDependencies": { "vitest": "^2.1.0", "typescript": "^5.5.0" }
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/dahoai/inkwire.git",
10
+ "directory": "inkwire/clients/node"
11
+ },
12
+ "main": "dist/index.js",
13
+ "types": "dist/index.d.ts",
14
+ "files": [
15
+ "dist/*.js",
16
+ "dist/*.d.ts"
17
+ ],
18
+ "scripts": {
19
+ "build": "tsc",
20
+ "test": "vitest run"
21
+ },
22
+ "devDependencies": {
23
+ "@types/node": "^20.19.43",
24
+ "typescript": "^5.5.0",
25
+ "vitest": "^2.1.0"
26
+ }
10
27
  }