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.
- package/README.md +53 -9
- package/package.json +24 -7
package/README.md
CHANGED
|
@@ -1,18 +1,62 @@
|
|
|
1
1
|
# inkwire-client
|
|
2
2
|
|
|
3
|
-
Node client for
|
|
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 {
|
|
6
|
+
import {
|
|
7
|
+
publish, capabilities, list, get, update, remove, terms, uploadMedia, listMedia, updateMedia, edits, isScheduled,
|
|
8
|
+
} from "inkwire-client";
|
|
7
9
|
|
|
8
|
-
const
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
markdown: "# Hello
|
|
12
|
-
|
|
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
|
-
|
|
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/
|
|
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",
|
|
3
|
-
"
|
|
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": {
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
}
|