@ulvio/client 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # @ulvio/client
 
-Official TypeScript client for the Ulvio platform, plus the html-to-pdf and utilities services.
+Official TypeScript client for the Ulvio platform.
 
-A single `Ulvio` class exposes domain-scoped sub-clients. Each backend service is configured independently and is **optional** — projects only need to set the URLs (and platform key) for the services they actually use.
+A single `Ulvio` class exposes domain-scoped sub-clients (mail, mailbox, sms, whatsapp, voice, files, ai, html-to-pdf, utilities), all reachable via the same `baseUrl` + `apiKey`. The platform proxies html-to-pdf and utilities to their internal services transparently, so consumers only need one set of credentials.
 
 ## Install
 
@@ -18,55 +18,26 @@ Requires Node.js **24+**.
 import { Ulvio } from '@ulvio/client';
 
 const client = new Ulvio({
-  // Platform — required for mail / mailbox / sms / whatsapp / voice / files / ai
-  platformApiUrl: process.env.ULVIO_PLATFORM_API_URL,
-  platformApiKey: process.env.ULVIO_PLATFORM_API_KEY,
-
-  // HTML-to-PDF — required for client.htmlToPdf.*
-  htmlToPdfApiUrl: process.env.HTML_TO_PDF_API_URL,
-
-  // Utilities (MJML / Liquid / Markdown) — required for client.utilities.*
-  utilitiesApiUrl: process.env.UTILITIES_API_URL,
+  baseUrl: process.env.ULVIO_BASE_URL,
+  apiKey: process.env.ULVIO_API_KEY,
 });
 ```
 
-| Sub-client | Requires |
-|---|---|
-| `client.mail`, `client.mailbox`, `client.sms`, `client.whatsapp`, `client.voice`, `client.files`, `client.ai` | `platformApiUrl` + `platformApiKey` |
-| `client.htmlToPdf` | `htmlToPdfApiUrl` |
-| `client.utilities` | `utilitiesApiUrl` |
-
-If you call a sub-client whose required config is missing, the call throws an `UlvioError` with one of:
-
-- `platform_not_configured`
-- `html_to_pdf_not_configured`
-- `utilities_not_configured`
-
-This is distinct from runtime/network errors, so consumers can detect misconfiguration explicitly:
+Both `baseUrl` and `apiKey` are required for every sub-client. If either is missing when a method is called, the call throws an `UlvioError` with code `not_configured` — distinct from runtime/network errors, so consumers can detect misconfiguration explicitly:
 
 ```ts
-import { UlvioError } from '@ulvio/client';
+import { UlvioError, NOT_CONFIGURED_CODE } from '@ulvio/client';
 
 try {
   await client.mail.sendTransactional({ ... });
 } catch (err) {
-  if (err instanceof UlvioError && err.code === 'platform_not_configured') {
+  if (err instanceof UlvioError && err.code === NOT_CONFIGURED_CODE) {
     // surface a deployment-time configuration error
   }
   throw err;
 }
 ```
 
-### Partial configuration
-
-A project that only needs html-to-pdf can construct the client with a single field:
-
-```ts
-const client = new Ulvio({ htmlToPdfApiUrl: 'http://html-to-pdf:3002' });
-await client.htmlToPdf.convert({ html: btoa('<h1>hi</h1>'), outputMode: 'base64' });
-// client.mail.* would throw platform_not_configured.
-```
-
 ## Usage
 
 ### Mail
@@ -174,6 +145,33 @@ const { html: md } = await client.utilities.renderMarkdown({ markdown: '# title'
 const { html: email } = await client.utilities.renderEmail({ mjml: '...', data: { ... } });
 ```
 
+## Migrating from 0.2.x to 0.3.0
+
+The 0.3.0 release collapses the four per-service config fields to a single `{ baseUrl, apiKey }` pair, and routes html-to-pdf and utilities through the platform forwarder.
+
+- Replace `platformApiUrl` / `htmlToPdfApiUrl` / `utilitiesApiUrl` with **one** `baseUrl` pointing at `api.ulvio.dev` (or your platform-dev URL).
+- Replace `platformApiKey` with `apiKey` — the same key now authenticates every sub-client.
+- The legacy env vars (`ULVIO_PLATFORM_API_URL`, `HTML_TO_PDF_API_URL`, `UTILITIES_API_URL`) should be replaced with `ULVIO_BASE_URL` + `ULVIO_API_KEY`.
+- The three legacy error codes (`platform_not_configured`, `html_to_pdf_not_configured`, `utilities_not_configured`) are gone; catch `not_configured` (exported as `NOT_CONFIGURED_CODE`) instead.
+
+```ts
+// before (0.2.x)
+new Ulvio({
+  platformApiUrl: process.env.ULVIO_PLATFORM_API_URL,
+  platformApiKey: process.env.ULVIO_PLATFORM_API_KEY,
+  htmlToPdfApiUrl: process.env.HTML_TO_PDF_API_URL,
+  utilitiesApiUrl: process.env.UTILITIES_API_URL,
+});
+
+// after (0.3.0)
+new Ulvio({
+  baseUrl: process.env.ULVIO_BASE_URL,
+  apiKey: process.env.ULVIO_API_KEY,
+});
+```
+
+The platform side must be running a version that exposes `/html-to-pdf/*` and `/utilities/*` forwarders (`ulvio-dev/platform` and `ulvio-dev/platform-dev`).
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -23,13 +23,11 @@ __export(index_exports, {
   AiClient: () => AiClient,
   CONNECTOR_UNHEALTHY_CODE: () => CONNECTOR_UNHEALTHY_CODE,
   FilesClient: () => FilesClient,
-  HTML_TO_PDF_NOT_CONFIGURED_CODE: () => HTML_TO_PDF_NOT_CONFIGURED_CODE,
   HtmlToPdfClient: () => HtmlToPdfClient,
   MailClient: () => MailClient,
   MailboxClient: () => MailboxClient,
-  PLATFORM_NOT_CONFIGURED_CODE: () => PLATFORM_NOT_CONFIGURED_CODE,
+  NOT_CONFIGURED_CODE: () => NOT_CONFIGURED_CODE,
   SmsClient: () => SmsClient,
-  UTILITIES_NOT_CONFIGURED_CODE: () => UTILITIES_NOT_CONFIGURED_CODE,
   Ulvio: () => Ulvio,
   UlvioError: () => UlvioError,
   UtilitiesClient: () => UtilitiesClient,
@@ -41,9 +39,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
 var CONNECTOR_UNHEALTHY_CODE = "CONNECTOR_UNHEALTHY";
-var PLATFORM_NOT_CONFIGURED_CODE = "platform_not_configured";
-var HTML_TO_PDF_NOT_CONFIGURED_CODE = "html_to_pdf_not_configured";
-var UTILITIES_NOT_CONFIGURED_CODE = "utilities_not_configured";
+var NOT_CONFIGURED_CODE = "not_configured";
 var UlvioError = class extends Error {
   code;
   status;
@@ -82,40 +78,20 @@ var HttpClient = class {
     this.config = config;
   }
   config;
-  requirePlatform(method) {
-    const url = this.config.platformApiUrl;
-    const key = this.config.platformApiKey;
+  requireConfig(method) {
+    const url = this.config.baseUrl;
+    const key = this.config.apiKey;
     if (!url || !key) {
+      const missing = !url && !key ? "baseUrl and apiKey" : !url ? "baseUrl" : "apiKey";
       throw new UlvioError(
-        PLATFORM_NOT_CONFIGURED_CODE,
-        `${method} requires platformApiUrl and platformApiKey to be set on the Ulvio client`
+        NOT_CONFIGURED_CODE,
+        `${method} requires ${missing} to be set on the Ulvio client`
       );
     }
     return { url: trimSlash(url), key };
   }
-  requireHtmlToPdf(method) {
-    const url = this.config.htmlToPdfApiUrl;
-    if (!url) {
-      throw new UlvioError(
-        HTML_TO_PDF_NOT_CONFIGURED_CODE,
-        `${method} requires htmlToPdfApiUrl to be set on the Ulvio client`
-      );
-    }
-    return trimSlash(url);
-  }
-  requireUtilities(method) {
-    const url = this.config.utilitiesApiUrl;
-    if (!url) {
-      throw new UlvioError(
-        UTILITIES_NOT_CONFIGURED_CODE,
-        `${method} requires utilitiesApiUrl to be set on the Ulvio client`
-      );
-    }
-    return trimSlash(url);
-  }
-  // ── Platform (authenticated) ──────────────────────────────────────────
-  async platformRequest(callerName, method, path, options = {}) {
-    const { url, key } = this.requirePlatform(callerName);
+  async request(callerName, method, path, options = {}) {
+    const { url, key } = this.requireConfig(callerName);
     const res = await fetch(`${url}${path}`, {
       method,
       headers: {
@@ -127,8 +103,8 @@ var HttpClient = class {
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
-  async platformRequestRaw(callerName, method, path, options = {}) {
-    const { url, key } = this.requirePlatform(callerName);
+  async requestRaw(callerName, method, path, options = {}) {
+    const { url, key } = this.requireConfig(callerName);
     const headers = { ...options.headers };
     if (options.contentType) headers["Content-Type"] = options.contentType;
     headers["Authorization"] = `Bearer ${key}`;
@@ -140,30 +116,6 @@ var HttpClient = class {
     if (!res.ok) throw await parseError(res);
     return res;
   }
-  // ── HTML-to-PDF (unauthenticated) ─────────────────────────────────────
-  async htmlToPdfFetch(callerName, path, init) {
-    const url = this.requireHtmlToPdf(callerName);
-    return fetch(`${url}${path}`, init);
-  }
-  // ── Utilities (unauthenticated) ───────────────────────────────────────
-  async utilitiesRequest(callerName, method, path, options = {}) {
-    const url = this.requireUtilities(callerName);
-    const res = await fetch(`${url}${path}`, {
-      method,
-      headers: { "Content-Type": "application/json" },
-      body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
-    });
-    const data = await res.json().catch(() => void 0);
-    if (!res.ok) {
-      const errBody = data;
-      throw new UlvioError(
-        errBody?.error?.code ?? "request_failed",
-        errBody?.error?.message ?? res.statusText,
-        { status: res.status, response: data }
-      );
-    }
-    return data;
-  }
 };
 
 // src/clients/mail.ts
@@ -173,7 +125,7 @@ var MailClient = class {
   }
   http;
   sendTransactional(params) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.mail.sendTransactional()",
       "POST",
       "/v1/transactional-mail/send",
@@ -189,7 +141,7 @@ var MailboxClient = class {
   }
   http;
   send(params) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.mailbox.send()",
       "POST",
       "/v1/mailbox/send",
@@ -198,21 +150,21 @@ var MailboxClient = class {
   }
   list(limit) {
     const qs = limit !== void 0 ? `?limit=${limit}` : "";
-    return this.http.platformRequest(
+    return this.http.request(
       "client.mailbox.list()",
       "GET",
       `/v1/mailbox/messages${qs}`
     );
   }
   get(id) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.mailbox.get()",
       "GET",
       `/v1/mailbox/messages/${encodeURIComponent(id)}`
     );
   }
   markProcessed(id) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.mailbox.markProcessed()",
       "POST",
       `/v1/mailbox/messages/${encodeURIComponent(id)}/mark-processed`
@@ -222,7 +174,7 @@ var MailboxClient = class {
    * Download a mailbox message attachment as a Buffer.
    */
   async getAttachment(messageId, attachmentId) {
-    const res = await this.http.platformRequestRaw(
+    const res = await this.http.requestRaw(
       "client.mailbox.getAttachment()",
       "GET",
       `/v1/mailbox/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`
@@ -231,7 +183,7 @@ var MailboxClient = class {
     return Buffer.from(arrayBuffer);
   }
   getConnectorStatus() {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.mailbox.getConnectorStatus()",
       "GET",
       "/v1/mailbox/connector-status"
@@ -241,7 +193,7 @@ var MailboxClient = class {
    * Dev-only: toggle the mock connector's health state.
    */
   setConnectorStatus(healthy) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.mailbox.setConnectorStatus()",
       "PATCH",
       "/v1/mailbox/connector-status",
@@ -257,7 +209,7 @@ var SmsClient = class {
   }
   http;
   send(params) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.sms.send()",
       "POST",
       "/v1/sms/send",
@@ -273,7 +225,7 @@ var WhatsAppClient = class {
   }
   http;
   send(params) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.whatsapp.send()",
       "POST",
       "/v1/whatsapp/send",
@@ -289,7 +241,7 @@ var VoiceClient = class {
   }
   http;
   transcribe(params) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.voice.transcribe()",
       "POST",
       "/v1/voice/send",
@@ -305,7 +257,7 @@ var FilesClient = class {
   }
   http;
   async upload(key, file, contentType = "application/octet-stream") {
-    const res = await this.http.platformRequestRaw(
+    const res = await this.http.requestRaw(
       "client.files.upload()",
       "PUT",
       `/v1/files/${encodeURI(key)}`,
@@ -317,7 +269,7 @@ var FilesClient = class {
    * Download a file. Returns the raw Response for streaming.
    */
   get(key) {
-    return this.http.platformRequestRaw(
+    return this.http.requestRaw(
       "client.files.get()",
       "GET",
       `/v1/files/${encodeURI(key)}`
@@ -329,21 +281,21 @@ var FilesClient = class {
     if (limit !== void 0) params.set("limit", String(limit));
     if (cursor) params.set("cursor", cursor);
     const qs = params.toString();
-    return this.http.platformRequest(
+    return this.http.request(
       "client.files.list()",
       "GET",
       `/v1/files${qs ? `?${qs}` : ""}`
     );
   }
   delete(key) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.files.delete()",
       "DELETE",
       `/v1/files/${encodeURI(key)}`
     );
   }
   deleteMany(prefix) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.files.deleteMany()",
       "DELETE",
       `/v1/files?prefix=${encodeURIComponent(prefix)}`
@@ -354,7 +306,7 @@ var FilesClient = class {
    * @param expiresIn TTL in seconds (default 3600, min 60, max 86400)
    */
   presignedDownloadUrl(key, expiresIn) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.files.presignedDownloadUrl()",
       "POST",
       "/v1/files/presigned-download",
@@ -367,7 +319,7 @@ var FilesClient = class {
    * @param maxSize Max file size in bytes (default 50MB)
    */
   presignedUploadUrl(key, contentType, expiresIn, maxSize) {
-    return this.http.platformRequest(
+    return this.http.request(
       "client.files.presignedUploadUrl()",
       "POST",
       "/v1/files/presigned-upload",
@@ -411,7 +363,7 @@ var AiClient = class {
   http;
   async parse(params) {
     const wire = buildPayload(params);
-    const response = await this.http.platformRequest(
+    const response = await this.http.request(
       "client.ai.parse()",
       "POST",
       "/v1/ai/parse",
@@ -421,7 +373,7 @@ var AiClient = class {
   }
   async *stream(params) {
     const wire = buildPayload(params);
-    const res = await this.http.platformRequestRaw(
+    const res = await this.http.requestRaw(
       "client.ai.stream()",
       "POST",
       "/v1/ai/stream",
@@ -493,19 +445,16 @@ var HtmlToPdfClient = class {
   }
   http;
   async convert(params, callbacks) {
-    const res = await this.http.htmlToPdfFetch("client.htmlToPdf.convert()", "/api/html-to-pdf", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(params)
-    });
-    if (!res.ok) {
-      const data = await res.json().catch(() => void 0);
-      throw new UlvioError(
-        data?.error?.code ?? "html_to_pdf_failed",
-        data?.error?.message ?? res.statusText,
-        { status: res.status, response: data }
-      );
-    }
+    const res = await this.http.requestRaw(
+      "client.htmlToPdf.convert()",
+      "POST",
+      "/html-to-pdf/convert",
+      {
+        body: JSON.stringify(params),
+        contentType: "application/json",
+        headers: { Accept: "text/event-stream" }
+      }
+    );
     if (!res.body) {
       throw new UlvioError("html_to_pdf_no_body", "html-to-pdf service returned no body", {
         status: res.status
@@ -555,42 +504,42 @@ var UtilitiesClient = class {
   }
   http;
   compileMjml(params) {
-    return this.http.utilitiesRequest(
+    return this.http.request(
       "client.utilities.compileMjml()",
       "POST",
-      "/api/mjml/compile",
+      "/utilities/mjml/compile",
       { body: params }
     );
   }
   renderLiquid(params) {
-    return this.http.utilitiesRequest(
+    return this.http.request(
       "client.utilities.renderLiquid()",
       "POST",
-      "/api/liquidjs/render",
+      "/utilities/liquidjs/render",
       { body: params }
     );
   }
   extractLiquidVariables(params) {
-    return this.http.utilitiesRequest(
+    return this.http.request(
       "client.utilities.extractLiquidVariables()",
       "POST",
-      "/api/liquidjs/variables",
+      "/utilities/liquidjs/variables",
       { body: params }
     );
   }
   renderMarkdown(params) {
-    return this.http.utilitiesRequest(
+    return this.http.request(
       "client.utilities.renderMarkdown()",
       "POST",
-      "/api/markdown/render",
+      "/utilities/markdown/render",
       { body: params }
     );
   }
   renderEmail(params) {
-    return this.http.utilitiesRequest(
+    return this.http.request(
       "client.utilities.renderEmail()",
       "POST",
-      "/api/render-email",
+      "/utilities/render-email",
       { body: params }
     );
   }
@@ -607,7 +556,7 @@ var Ulvio = class {
   ai;
   htmlToPdf;
   utilities;
-  constructor(config = {}) {
+  constructor(config) {
     const http = new HttpClient(config);
     this.mail = new MailClient(http);
     this.mailbox = new MailboxClient(http);
@@ -625,13 +574,11 @@ var Ulvio = class {
   AiClient,
   CONNECTOR_UNHEALTHY_CODE,
   FilesClient,
-  HTML_TO_PDF_NOT_CONFIGURED_CODE,
   HtmlToPdfClient,
   MailClient,
   MailboxClient,
-  PLATFORM_NOT_CONFIGURED_CODE,
+  NOT_CONFIGURED_CODE,
   SmsClient,
-  UTILITIES_NOT_CONFIGURED_CODE,
   Ulvio,
   UlvioError,
   UtilitiesClient,