@clawnify/services 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+interface ServicesEnv {
+    CLAWNIFY_TOKEN?: string;
+    /** Base URL override, for a local fake in tests. Default https://services.clawnify.com. */
+    CLAWNIFY_SERVICES_URL?: string;
+}
+/**
+ * A failed call. `code` is the service's own error code: `invalid_token`,
+ * `quota_exceeded`, `render_failed`, … and `body` the whole answer, which for
+ * `quota_exceeded` carries `limit`, `used` and `resets_at`.
+ */
+declare class ClawnifyServicesError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly body?: Record<string, unknown>;
+    constructor(message: string, opts?: {
+        status?: number;
+        code?: string;
+        body?: Record<string, unknown>;
+    });
+}
+/** A render the service stored for you, served from a presigned link (`output: "url"`). */
+interface StoredFile {
+    url: string;
+    key: string;
+    expires_at: string;
+    size: number;
+    content_type: string;
+}
+interface Viewport {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}
+type WaitUntil = "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+interface CallOptions {
+    signal?: AbortSignal;
+}
+/** Ask for a link instead of the bytes: for callers that can't hold or pass the file on themselves. */
+interface AsLink {
+    output: "url";
+    /** Download name. */
+    filename?: string;
+    /** Link lifetime in seconds, at most 7 days. */
+    expiresIn?: number;
+}
+type PaperFormat = "Letter" | "Legal" | "Tabloid" | "Ledger" | "A0" | "A1" | "A2" | "A3" | "A4" | "A5" | "A6";
+interface RenderPDFOptions extends CallOptions {
+    html: string;
+    format?: PaperFormat;
+    margin?: {
+        top?: string;
+        right?: string;
+        bottom?: string;
+        left?: string;
+    };
+    landscape?: boolean;
+    printBackground?: boolean;
+    scale?: number;
+    /** Exact page size, e.g. "1280px"; wins over `format`. For fixed-canvas documents like slides. */
+    width?: string;
+    height?: string;
+    /** Use the document's own CSS `@page { size }`. */
+    preferCSSPageSize?: boolean;
+    /** Browser viewport, for layouts that scale to it (pin it to the canvas size). */
+    viewport?: Viewport;
+}
+/** HTML to a PDF: the bytes, or with `output: "url"` a link to it. */
+declare function renderPDF(env: ServicesEnv, opts: RenderPDFOptions & {
+    output?: "bytes";
+}): Promise<Uint8Array>;
+declare function renderPDF(env: ServicesEnv, opts: RenderPDFOptions & AsLink): Promise<StoredFile>;
+type ImageType = "png" | "jpeg" | "webp";
+interface ScreenshotBase extends CallOptions {
+    /** Capture size; or pass a full `viewport`. */
+    width?: number;
+    height?: number;
+    viewport?: Viewport;
+    /** Default png. */
+    type?: ImageType;
+    /** The whole scrollable page, not just the viewport. */
+    fullPage?: boolean;
+    /** Transparent background (png, webp). */
+    omitBackground?: boolean;
+    /** 0 to 100, jpeg and webp only. */
+    quality?: number;
+    /** Capture once this CSS selector exists, for pages that finish rendering in script. */
+    waitForSelector?: string;
+    gotoWaitUntil?: WaitUntil;
+}
+/** Markup you supply, or a live public https page, never both. */
+type RenderScreenshotOptions = ScreenshotBase & ({
+    html: string;
+    url?: never;
+} | {
+    url: string;
+    html?: never;
+});
+/** Markup or a live page to an image: the bytes, or with `output: "url"` a link to it. */
+declare function renderScreenshot(env: ServicesEnv, opts: RenderScreenshotOptions & {
+    output?: "bytes";
+}): Promise<Uint8Array>;
+declare function renderScreenshot(env: ServicesEnv, opts: RenderScreenshotOptions & AsLink): Promise<StoredFile>;
+interface RenderMarkdownOptions extends CallOptions {
+    /** A public https page. It is rendered first, so a page built by script reads like a static one. */
+    url: string;
+    /** Cut the markdown to this many characters (the service caps it at 50,000). */
+    maxChars?: number;
+    gotoWaitUntil?: WaitUntil;
+}
+interface MarkdownPage {
+    url: string;
+    markdown: string;
+    chars: number;
+    truncated: boolean;
+}
+/** A live page's content as markdown, for example as a model's context. */
+declare function renderMarkdown(env: ServicesEnv, opts: RenderMarkdownOptions): Promise<MarkdownPage>;
+
+export { ClawnifyServicesError, type ImageType, type MarkdownPage, type PaperFormat, type RenderMarkdownOptions, type RenderPDFOptions, type RenderScreenshotOptions, type ServicesEnv, type StoredFile, type Viewport, type WaitUntil, renderMarkdown, renderPDF, renderScreenshot };

package/dist/index.js

@@ -0,0 +1,91 @@
+// src/index.ts
+var ClawnifyServicesError = class extends Error {
+  status;
+  code;
+  body;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "ClawnifyServicesError";
+    this.status = opts.status;
+    this.code = opts.code;
+    this.body = opts.body;
+  }
+};
+var DEFAULT_URL = "https://services.clawnify.com";
+async function post(env, path, body, signal) {
+  if (!env.CLAWNIFY_TOKEN) {
+    throw new ClawnifyServicesError("CLAWNIFY_TOKEN is not set, so Clawnify services are unavailable.");
+  }
+  const base = (env.CLAWNIFY_SERVICES_URL || DEFAULT_URL).replace(/\/+$/, "");
+  const res = await fetch(`${base}${path}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${env.CLAWNIFY_TOKEN}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal
+  });
+  if (!res.ok) {
+    const parsed = await res.json().catch(() => null);
+    const answer = parsed && typeof parsed === "object" ? parsed : void 0;
+    const code = typeof answer?.error === "string" ? answer.error : void 0;
+    const detail = typeof answer?.detail === "string" ? answer.detail : void 0;
+    throw new ClawnifyServicesError(detail || code || `${path} answered ${res.status}`, { status: res.status, code, body: answer });
+  }
+  return res;
+}
+async function deliver(res, output) {
+  return output === "url" ? await res.json() : new Uint8Array(await res.arrayBuffer());
+}
+async function renderPDF(env, opts) {
+  const link = opts.output === "url" ? opts : void 0;
+  const res = await post(env, "/pdf/render", {
+    html: opts.html,
+    format: opts.format,
+    margin: opts.margin,
+    landscape: opts.landscape,
+    print_background: opts.printBackground,
+    scale: opts.scale,
+    width: opts.width,
+    height: opts.height,
+    prefer_css_page_size: opts.preferCSSPageSize,
+    viewport: opts.viewport,
+    output: opts.output,
+    filename: link?.filename,
+    expires_in: link?.expiresIn
+  }, opts.signal);
+  return deliver(res, opts.output);
+}
+async function renderScreenshot(env, opts) {
+  const link = opts.output === "url" ? opts : void 0;
+  const res = await post(env, "/screenshot/render", {
+    html: opts.html,
+    url: opts.url,
+    width: opts.width,
+    height: opts.height,
+    viewport: opts.viewport,
+    type: opts.type,
+    full_page: opts.fullPage,
+    omit_background: opts.omitBackground,
+    quality: opts.quality,
+    wait_for_selector: opts.waitForSelector,
+    goto_wait_until: opts.gotoWaitUntil,
+    output: opts.output,
+    filename: link?.filename,
+    expires_in: link?.expiresIn
+  }, opts.signal);
+  return deliver(res, opts.output);
+}
+async function renderMarkdown(env, opts) {
+  const res = await post(env, "/markdown/render", {
+    url: opts.url,
+    max_chars: opts.maxChars,
+    goto_wait_until: opts.gotoWaitUntil
+  }, opts.signal);
+  return await res.json();
+}
+export {
+  ClawnifyServicesError,
+  renderMarkdown,
+  renderPDF,
+  renderScreenshot
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @clawnify/services — call Clawnify's managed services (services.clawnify.com)\n// from a deployed app.\n//\n// One client for every service: the org's CLAWNIFY_TOKEN, injected into every\n// app at build, authorizes each call, and each call counts against the org's\n// monthly quota for that service. A function exists here for each route an app\n// calls; add one next to its siblings when a new service gets its first caller.\n// The queue has its own package, @clawnify/queue.\n\nexport interface ServicesEnv {\n  CLAWNIFY_TOKEN?: string;\n  /** Base URL override, for a local fake in tests. Default https://services.clawnify.com. */\n  CLAWNIFY_SERVICES_URL?: string;\n}\n\n/**\n * A failed call. `code` is the service's own error code: `invalid_token`,\n * `quota_exceeded`, `render_failed`, … and `body` the whole answer, which for\n * `quota_exceeded` carries `limit`, `used` and `resets_at`.\n */\nexport class ClawnifyServicesError extends Error {\n  readonly status?: number;\n  readonly code?: string;\n  readonly body?: Record<string, unknown>;\n  constructor(message: string, opts: { status?: number; code?: string; body?: Record<string, unknown> } = {}) {\n    super(message);\n    this.name = \"ClawnifyServicesError\";\n    this.status = opts.status;\n    this.code = opts.code;\n    this.body = opts.body;\n  }\n}\n\n/** A render the service stored for you, served from a presigned link (`output: \"url\"`). */\nexport interface StoredFile {\n  url: string;\n  key: string;\n  expires_at: string;\n  size: number;\n  content_type: string;\n}\n\nexport interface Viewport {\n  width: number;\n  height: number;\n  deviceScaleFactor?: number;\n}\n\nexport type WaitUntil = \"load\" | \"domcontentloaded\" | \"networkidle0\" | \"networkidle2\";\n\ninterface CallOptions {\n  signal?: AbortSignal;\n}\n\n/** Ask for a link instead of the bytes: for callers that can't hold or pass the file on themselves. */\ninterface AsLink {\n  output: \"url\";\n  /** Download name. */\n  filename?: string;\n  /** Link lifetime in seconds, at most 7 days. */\n  expiresIn?: number;\n}\n\nconst DEFAULT_URL = \"https://services.clawnify.com\";\n\nasync function post(env: ServicesEnv, path: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<Response> {\n  if (!env.CLAWNIFY_TOKEN) {\n    throw new ClawnifyServicesError(\"CLAWNIFY_TOKEN is not set, so Clawnify services are unavailable.\");\n  }\n  const base = (env.CLAWNIFY_SERVICES_URL || DEFAULT_URL).replace(/\\/+$/, \"\");\n  const res = await fetch(`${base}${path}`, {\n    method: \"POST\",\n    headers: { Authorization: `Bearer ${env.CLAWNIFY_TOKEN}`, \"Content-Type\": \"application/json\" },\n    body: JSON.stringify(body),\n    signal,\n  });\n  if (!res.ok) {\n    const parsed = (await res.json().catch(() => null)) as Record<string, unknown> | null;\n    const answer = parsed && typeof parsed === \"object\" ? parsed : undefined;\n    const code = typeof answer?.error === \"string\" ? answer.error : undefined;\n    const detail = typeof answer?.detail === \"string\" ? answer.detail : undefined;\n    throw new ClawnifyServicesError(detail || code || `${path} answered ${res.status}`, { status: res.status, code, body: answer });\n  }\n  return res;\n}\n\nasync function deliver(res: Response, output: \"bytes\" | \"url\" | undefined): Promise<Uint8Array | StoredFile> {\n  return output === \"url\" ? ((await res.json()) as StoredFile) : new Uint8Array(await res.arrayBuffer());\n}\n\n// ── PDF ──────────────────────────────────────────────────────────────────────\n\nexport type PaperFormat = \"Letter\" | \"Legal\" | \"Tabloid\" | \"Ledger\" | \"A0\" | \"A1\" | \"A2\" | \"A3\" | \"A4\" | \"A5\" | \"A6\";\n\nexport interface RenderPDFOptions extends CallOptions {\n  html: string;\n  format?: PaperFormat;\n  margin?: { top?: string; right?: string; bottom?: string; left?: string };\n  landscape?: boolean;\n  printBackground?: boolean;\n  scale?: number;\n  /** Exact page size, e.g. \"1280px\"; wins over `format`. For fixed-canvas documents like slides. */\n  width?: string;\n  height?: string;\n  /** Use the document's own CSS `@page { size }`. */\n  preferCSSPageSize?: boolean;\n  /** Browser viewport, for layouts that scale to it (pin it to the canvas size). */\n  viewport?: Viewport;\n}\n\n/** HTML to a PDF: the bytes, or with `output: \"url\"` a link to it. */\nexport function renderPDF(env: ServicesEnv, opts: RenderPDFOptions & { output?: \"bytes\" }): Promise<Uint8Array>;\nexport function renderPDF(env: ServicesEnv, opts: RenderPDFOptions & AsLink): Promise<StoredFile>;\nexport async function renderPDF(\n  env: ServicesEnv,\n  opts: RenderPDFOptions & ({ output?: \"bytes\" } | AsLink),\n): Promise<Uint8Array | StoredFile> {\n  const link = opts.output === \"url\" ? (opts as AsLink) : undefined;\n  const res = await post(env, \"/pdf/render\", {\n    html: opts.html,\n    format: opts.format,\n    margin: opts.margin,\n    landscape: opts.landscape,\n    print_background: opts.printBackground,\n    scale: opts.scale,\n    width: opts.width,\n    height: opts.height,\n    prefer_css_page_size: opts.preferCSSPageSize,\n    viewport: opts.viewport,\n    output: opts.output,\n    filename: link?.filename,\n    expires_in: link?.expiresIn,\n  }, opts.signal);\n  return deliver(res, opts.output);\n}\n\n// ── Screenshot ───────────────────────────────────────────────────────────────\n\nexport type ImageType = \"png\" | \"jpeg\" | \"webp\";\n\ninterface ScreenshotBase extends CallOptions {\n  /** Capture size; or pass a full `viewport`. */\n  width?: number;\n  height?: number;\n  viewport?: Viewport;\n  /** Default png. */\n  type?: ImageType;\n  /** The whole scrollable page, not just the viewport. */\n  fullPage?: boolean;\n  /** Transparent background (png, webp). */\n  omitBackground?: boolean;\n  /** 0 to 100, jpeg and webp only. */\n  quality?: number;\n  /** Capture once this CSS selector exists, for pages that finish rendering in script. */\n  waitForSelector?: string;\n  gotoWaitUntil?: WaitUntil;\n}\n\n/** Markup you supply, or a live public https page, never both. */\nexport type RenderScreenshotOptions = ScreenshotBase & ({ html: string; url?: never } | { url: string; html?: never });\n\n/** Markup or a live page to an image: the bytes, or with `output: \"url\"` a link to it. */\nexport function renderScreenshot(env: ServicesEnv, opts: RenderScreenshotOptions & { output?: \"bytes\" }): Promise<Uint8Array>;\nexport function renderScreenshot(env: ServicesEnv, opts: RenderScreenshotOptions & AsLink): Promise<StoredFile>;\nexport async function renderScreenshot(\n  env: ServicesEnv,\n  opts: RenderScreenshotOptions & ({ output?: \"bytes\" } | AsLink),\n): Promise<Uint8Array | StoredFile> {\n  const link = opts.output === \"url\" ? (opts as AsLink) : undefined;\n  const res = await post(env, \"/screenshot/render\", {\n    html: opts.html,\n    url: opts.url,\n    width: opts.width,\n    height: opts.height,\n    viewport: opts.viewport,\n    type: opts.type,\n    full_page: opts.fullPage,\n    omit_background: opts.omitBackground,\n    quality: opts.quality,\n    wait_for_selector: opts.waitForSelector,\n    goto_wait_until: opts.gotoWaitUntil,\n    output: opts.output,\n    filename: link?.filename,\n    expires_in: link?.expiresIn,\n  }, opts.signal);\n  return deliver(res, opts.output);\n}\n\n// ── Markdown ─────────────────────────────────────────────────────────────────\n\nexport interface RenderMarkdownOptions extends CallOptions {\n  /** A public https page. It is rendered first, so a page built by script reads like a static one. */\n  url: string;\n  /** Cut the markdown to this many characters (the service caps it at 50,000). */\n  maxChars?: number;\n  gotoWaitUntil?: WaitUntil;\n}\n\nexport interface MarkdownPage {\n  url: string;\n  markdown: string;\n  chars: number;\n  truncated: boolean;\n}\n\n/** A live page's content as markdown, for example as a model's context. */\nexport async function renderMarkdown(env: ServicesEnv, opts: RenderMarkdownOptions): Promise<MarkdownPage> {\n  const res = await post(env, \"/markdown/render\", {\n    url: opts.url,\n    max_chars: opts.maxChars,\n    goto_wait_until: opts.gotoWaitUntil,\n  }, opts.signal);\n  return (await res.json()) as MarkdownPage;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@clawnify/services",
+  "version": "0.1.0",
+  "description": "Call Clawnify's managed services (PDF, screenshots, page markdown) from a deployed app.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run"
+  }
+}