inkwire-client 0.3.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.
Files changed (2) hide show
  1. package/README.md +53 -9
  2. package/package.json +24 -7
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. Pass `opts.fetch` to send through your own fetch, for example an SSRF-guarded one when the site URL comes from your users.
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/package.json CHANGED
@@ -1,10 +1,27 @@
1
1
  {
2
- "name": "inkwire-client", "version": "0.3.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": "git+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
  }