@ulvio/client 0.1.0

package/README.md

@@ -0,0 +1,201 @@
+# @ulvio/client
+
+Official TypeScript client for the Ulvio platform, plus the html-to-pdf and utilities services.
+
+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.
+
+## Install
+
+```bash
+npm install @ulvio/client
+```
+
+Requires Node.js **24+**.
+
+## Configuration
+
+```ts
+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,
+});
+```
+
+| 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:
+
+```ts
+import { UlvioError } from '@ulvio/client';
+
+try {
+  await client.mail.sendTransactional({ ... });
+} catch (err) {
+  if (err instanceof UlvioError && err.code === 'platform_not_configured') {
+    // 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
+
+```ts
+await client.mail.sendTransactional({
+  from: 'noreply@example.com',
+  to: ['user@example.com'],
+  subject: 'Welcome',
+  body_html: '<p>Hi!</p>',
+});
+```
+
+### Mailbox
+
+```ts
+const { messages } = await client.mailbox.list(20);
+const msg = await client.mailbox.get(messages[0].id);
+await client.mailbox.markProcessed(msg.id);
+```
+
+`getConnectorStatus()` reports whether the upstream connector is healthy. When unhealthy, the listing/reading methods throw an `UlvioError` whose `code` is `CONNECTOR_UNHEALTHY` — use the `isConnectorUnhealthyError` helper to detect it:
+
+```ts
+import { isConnectorUnhealthyError } from '@ulvio/client';
+
+try {
+  await client.mailbox.list();
+} catch (err) {
+  if (isConnectorUnhealthyError(err)) {
+    // back off polling
+  } else {
+    throw err;
+  }
+}
+```
+
+### SMS / WhatsApp / Voice
+
+```ts
+await client.sms.send({ from: '+1...', to: '+1...', body: 'hello' });
+await client.whatsapp.send({ to: '+1...', template_name: 'reminder', language_code: 'en' });
+await client.voice.transcribe({ file: base64Audio, file_name: 'call.webm' });
+```
+
+### Files
+
+```ts
+await client.files.upload('reports/2026/q1.pdf', buffer, 'application/pdf');
+const res = await client.files.get('reports/2026/q1.pdf');
+const { url } = await client.files.presignedDownloadUrl('reports/2026/q1.pdf', 600);
+```
+
+### AI proxy
+
+```ts
+import { z } from 'zod';
+
+const Person = z.object({ name: z.string(), age: z.number() });
+
+const data = await client.ai.parse({
+  model: 'claude-opus-4-7',
+  input: 'Extract the person from: "Ada Lovelace, 36"',
+  schema: Person,
+});
+
+for await (const event of client.ai.stream({
+  model: 'claude-opus-4-7',
+  input: '...',
+  schema: Person,
+})) {
+  if (event.type === 'partial') console.log(event.data);
+  if (event.type === 'complete') console.log('done', event.data);
+}
+```
+
+### HTML-to-PDF
+
+```ts
+const { pdf } = await client.htmlToPdf.convert(
+  { html: btoa('<h1>Invoice</h1>'), outputMode: 'base64' },
+  {
+    onQueued: ({ position }) => console.log('queued at', position),
+    onProcessing: ({ progress }) => console.log('progress', progress),
+  },
+);
+```
+
+Or have the service PUT the rendered PDF directly to a presigned URL:
+
+```ts
+await client.htmlToPdf.convert({
+  sourceUrl: 'https://example.com/invoice/1',
+  uploadUrl: presignedPutUrl,
+});
+```
+
+### Utilities
+
+```ts
+const { html } = await client.utilities.compileMjml({ mjml: '...' });
+const { result } = await client.utilities.renderLiquid({ template: 'Hi {{ name }}', data: { name: 'Ada' } });
+const { variables } = await client.utilities.extractLiquidVariables({ template: '{{ a }} {{ b }}' });
+const { html: md } = await client.utilities.renderMarkdown({ markdown: '# title' });
+const { html: email } = await client.utilities.renderEmail({ mjml: '...', data: { ... } });
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+End-to-end tests run against live containers via Docker Compose:
+
+```bash
+npm run test:e2e
+```
+
+## Releasing
+
+Tag the commit with the version (`vX.Y.Z`); the `Release` workflow verifies the tag matches `package.json` and runs `npm publish --provenance`.
+
+```bash
+npm version patch   # bumps package.json + creates a vX.Y.Z tag
+git push --follow-tags
+```
+
+The workflow needs an `NPM_TOKEN` secret with publish access to the `@ulvio` scope.