@prosewire/sdk 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @prosewire/sdk
 
+## 0.4.0
+
+### Minor Changes
+
+- c5310e0: Add post revision history and confirmed restore operations. Restores save the current post first and are available through the dashboard, management API, SDK, CLI, and MCP server.
+- 01df471: Add streamed create-only Prosewire portable imports with preview and explicit apply. Import JSON v2 plus managed original media, remap publication relationships and saved revisions, preserve slugs and dates, and default imported posts to drafts. Matching unchanged imports are safely retryable; collisions never overwrite existing content.
+  
+  The SDK adds `imports.run` and the Node-only `@prosewire/sdk/import-node` file helper. The CLI adds `import --data ... --media ...`, `--apply`, and `--preserve-states`. MCP adds the approval-gated `publication_import` tool. This capability requires a deployment containing the corresponding import endpoint.
+- 7e23d93: Expose configured publication languages and let the server apply each publication's default language when a post create request omits its locale.
+- 78fdf77: Add managed media upload, validation, processing, CDN metadata, quota, reference, deletion, and export workflows across the management clients.
+
+### Patch Changes
+
+- a6a9f37: Decode typed HTTP 409 post conflicts from the shared private API contract.
+- 27532b0: Upgrade the published Effect-based clients and tools to Effect 4.0.0-rc.112.
+- 99a284f: Document and enforce the optional publication assertion on authenticated post listings.
+- 93d88b7: Reject impossible calendar dates in post scheduling inputs and share post field validation with dashboard and application commands.
+- 48d27cf: Update Effect to 4.0.0-rc.115 across the SDK, CLI, and MCP server. Adapt CLI
+  arguments, flags, and MCP environment configuration to the renamed Effect
+  constructors while preserving existing commands and settings.
+  
+  Use explicit Next.js module extensions so the published reader package can be
+  imported by Node.js ES module consumers.
+- 8528b33: Return a structured invalid-revision error when historical revision data cannot be decoded, instead of an unclassified server failure.
+
+## 0.3.0
+
+### Minor Changes
+
+- 433ad8b: Add first-class, headless Next.js and Astro readers, monorepo-aware framework scaffolding, and public redirect resolution for static and server-rendered integrations.
+
+### Patch Changes
+
+- 15bf694: Harden package documentation with corrected response shapes, complete operation boundaries, configuration details, and safer integration guidance.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,10 @@
 
 Typed clients for Prosewire's authenticated management API and public content API.
 
+The package is pre-1.0. Pin a compatible version and review the changelog before upgrading.
+
+Full guide: [Build a native reader with TypeScript](https://prosewire.com/docs/integrate/typescript/)
+
 ## Install
 
 ```sh
@@ -21,12 +25,31 @@ const publicContent = createPublicClient({
 });
 
 const page = await publicContent.listPosts({ page: 1, pageSize: 20 });
-console.log(page.items.map((post) => post.title));
+console.log(page.posts.map((post) => post.title));
+```
+
+Filter lists and retrieve JSON or rendered HTML:
+
+```ts
+const page = await publicContent.listPosts({
+  search: "portable",
+  category: "engineering",
+  page: 1,
+  pageSize: 20,
+});
+
+console.log(page.posts.map((post) => post.title));
+const article = await publicContent.getPost("welcome");
+const resolution = await publicContent.resolvePost("old-welcome-slug");
+const redirects = await publicContent.listRedirects();
+const html = await publicContent.getRendered("welcome");
 ```
 
-Public clients do not require a key. For private management operations, create a
-publication-scoped API key in **Settings → Developer** and keep it on a trusted
-server:
+Public clients need no key and only return published content whose publication time has arrived. `pageSize` is capped at 100. `listAllPosts` follows every page for static builds, while `resolvePost` preserves the difference between a canonical post, redirect, and 404. The deprecated `limit` option remains an alias for `pageSize`.
+
+## Manage a publication
+
+Create a publication-scoped API key in **Integrate → Scoped API keys** and keep it on a trusted server:
 
 ```ts
 import { createClient } from "@prosewire/sdk";
@@ -39,6 +62,38 @@ const management = createClient({
 const drafts = await management.posts.list({ status: "draft" });
 ```
 
+Available Promise operations are:
+
+- `imports.run()` (streamed portable import, `content:write`)
+- `health()`
+- `blogs.list()`
+- `posts.list()`, `posts.get()`, and `posts.create()`
+- `posts.update()` and `posts.archive()`
+- `posts.revisions()` and `posts.restore()`
+- `media.list()`, `media.get()`, and `media.startUpload()`
+- `media.completeUpload()` and `media.delete()`
+
+Management keys are publication-scoped. Post, revision, and media reads require `content:read`. Create, update, archive, revision restore, and media mutations require `content:write`. A restore saves the current post as a new revision before replacing it. Media deletion fails while a current post references the asset. Never expose a management key or signed upload reservation in untrusted code.
+
+Start a managed upload with the publication UUID, filename, MIME type, and exact byte count. Send the bytes to the returned signed URL using its method and headers, then call `media.completeUpload()` with the reserved asset ID. Completion returns the sanitized variants and CDN URL.
+
+The optional `blog` value on `posts.list()` is a safety assertion. It must match the API key's publication slug or UUID; it cannot select another publication.
+
 For Effect applications, `createEffectClient` exposes the same operations as
 typed Effects. `createClient` is the Promise-compatible facade for existing
-callers; both are generated from the shared Effect HttpApi contract.
+callers; both share the Effect HttpApi contract; portable import uses its own streaming adapter and shared report/error schemas.
+
+Non-success responses reject. Public-client errors include the HTTP status; management errors retain the typed Effect HTTP API failure when using `createEffectClient`.
+
+## Portable import
+
+```ts
+import { openPortableImportFile } from "@prosewire/sdk/import-node";
+
+const preview = await management.imports.run({
+  ...openPortableImportFile("export.json", "media.zip"),
+  mode: "preview",
+});
+```
+
+The main entrypoint accepts a `ReadableStream<Uint8Array>` and `application/json` or `application/zip`; the Node-only helper streams local export artifacts. Explicit `mode: "apply"` creates content, with posts defaulting to drafts unless `preserveStates: true` is supplied. Failures retain `status`, `item`, and `reason` in `ProsewireImportError`. See [portable import](https://prosewire.com/docs/operate/portable-import/) for supported formats, limits, and exact-artifact retry policy.

package/dist/import-node.d.mts

@@ -0,0 +1,6 @@
+import { r as PortableImportInput } from "./index-BFz3f-oC.mjs";
+//#region src/import-node.d.ts
+/** Stream the existing two export artifacts into one envelope, without unpacking them. */
+export declare function openPortableImportFile(file: string, mediaFile?: string): Pick<PortableImportInput, "body" | "contentType">;
+//#endregion
+//# sourceMappingURL=import-node.d.mts.map

package/dist/import-node.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-node.d.mts","names":[],"sources":["../src/import-node.ts"],"mappings":";;;wBAMgB,uBACd,cACA,qBACC,KAAK"}

package/dist/import-node.mjs

@@ -0,0 +1,49 @@
+import { createReadStream } from "node:fs";
+import { Readable } from "node:stream";
+import { Zip, ZipPassThrough } from "fflate";
+//#region src/import-node.ts
+/** Stream the existing two export artifacts into one envelope, without unpacking them. */
+function openPortableImportFile(file, mediaFile) {
+	if (!mediaFile) return {
+		body: Readable.toWeb(createReadStream(file)),
+		contentType: file.toLowerCase().endsWith(".zip") ? "application/zip" : "application/json"
+	};
+	const mediaSource = mediaFile;
+	async function* chunks() {
+		const output = [];
+		let failure;
+		const archive = new Zip((error, chunk) => {
+			if (error) failure = error;
+			else output.push(chunk);
+		});
+		const drain = function* () {
+			if (failure) throw failure;
+			yield* output.splice(0);
+		};
+		try {
+			for (const [name, source] of [["export.json", file], ["media.zip", mediaSource]]) {
+				const entry = new ZipPassThrough(name);
+				archive.add(entry);
+				yield* drain();
+				for await (const chunk of createReadStream(source)) {
+					entry.push(chunk, false);
+					yield* drain();
+				}
+				entry.push(/* @__PURE__ */ new Uint8Array(), true);
+				yield* drain();
+			}
+			archive.end();
+			yield* drain();
+		} finally {
+			archive.terminate();
+		}
+	}
+	return {
+		contentType: "application/zip",
+		body: Readable.toWeb(Readable.from(chunks()))
+	};
+}
+//#endregion
+export { openPortableImportFile };
+
+//# sourceMappingURL=import-node.mjs.map

package/dist/import-node.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-node.mjs","names":[],"sources":["../src/import-node.ts"],"sourcesContent":["import { createReadStream } from \"node:fs\";\nimport { Readable } from \"node:stream\";\nimport { Zip, ZipPassThrough } from \"fflate\";\nimport type { PortableImportInput } from \"./index.ts\";\n\n/** Stream the existing two export artifacts into one envelope, without unpacking them. */\nexport function openPortableImportFile(\n  file: string,\n  mediaFile?: string,\n): Pick<PortableImportInput, \"body\" | \"contentType\"> {\n  if (!mediaFile)\n    return {\n      body: Readable.toWeb(\n        createReadStream(file),\n      ) as ReadableStream<Uint8Array>,\n      contentType: file.toLowerCase().endsWith(\".zip\")\n        ? \"application/zip\"\n        : \"application/json\",\n    };\n  const mediaSource = mediaFile;\n  async function* chunks() {\n    const output: Uint8Array[] = [];\n    let failure: Error | undefined;\n    const archive = new Zip((error, chunk) => {\n      if (error) failure = error;\n      else output.push(chunk);\n    });\n    const drain = function* () {\n      if (failure) throw failure;\n      yield* output.splice(0);\n    };\n    try {\n      for (const [name, source] of [\n        [\"export.json\", file],\n        [\"media.zip\", mediaSource],\n      ] as const) {\n        const entry = new ZipPassThrough(name);\n        archive.add(entry);\n        yield* drain();\n        for await (const chunk of createReadStream(source)) {\n          entry.push(chunk, false);\n          yield* drain();\n        }\n        entry.push(new Uint8Array(), true);\n        yield* drain();\n      }\n      archive.end();\n      yield* drain();\n    } finally {\n      archive.terminate();\n    }\n  }\n  return {\n    contentType: \"application/zip\",\n    body: Readable.toWeb(Readable.from(chunks())) as ReadableStream<Uint8Array>,\n  };\n}\n"],"mappings":";;;;;AAMA,SAAgB,uBACd,MACA,WACmD;CACnD,IAAI,CAAC,WACH,OAAO;EACL,MAAM,SAAS,MACb,iBAAiB,IAAI,CACvB;EACA,aAAa,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,IAC3C,oBACA;CACN;CACF,MAAM,cAAc;CACpB,gBAAgB,SAAS;EACvB,MAAM,SAAuB,CAAC;EAC9B,IAAI;EACJ,MAAM,UAAU,IAAI,KAAK,OAAO,UAAU;GACxC,IAAI,OAAO,UAAU;QAChB,OAAO,KAAK,KAAK;EACxB,CAAC;EACD,MAAM,QAAQ,aAAa;GACzB,IAAI,SAAS,MAAM;GACnB,OAAO,OAAO,OAAO,CAAC;EACxB;EACA,IAAI;GACF,KAAK,MAAM,CAAC,MAAM,WAAW,CAC3B,CAAC,eAAe,IAAI,GACpB,CAAC,aAAa,WAAW,CAC3B,GAAY;IACV,MAAM,QAAQ,IAAI,eAAe,IAAI;IACrC,QAAQ,IAAI,KAAK;IACjB,OAAO,MAAM;IACb,WAAW,MAAM,SAAS,iBAAiB,MAAM,GAAG;KAClD,MAAM,KAAK,OAAO,KAAK;KACvB,OAAO,MAAM;IACf;IACA,MAAM,qBAAK,IAAI,WAAW,GAAG,IAAI;IACjC,OAAO,MAAM;GACf;GACA,QAAQ,IAAI;GACZ,OAAO,MAAM;EACf,UAAU;GACR,QAAQ,UAAU;EACpB;CACF;CACA,OAAO;EACL,aAAa;EACb,MAAM,SAAS,MAAM,SAAS,KAAK,OAAO,CAAC,CAAC;CAC9C;AACF"}