@ulvio/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+import { z } from 'zod';
+
+interface UlvioConfig {
+    platformApiUrl?: string;
+    platformApiKey?: string;
+    htmlToPdfApiUrl?: string;
+    utilitiesApiUrl?: string;
+}
+interface RequestOptions {
+    body?: unknown;
+}
+interface RequestRawOptions {
+    body?: BodyInit;
+    contentType?: string;
+    headers?: Record<string, string>;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: UlvioConfig);
+    private requirePlatform;
+    private requireHtmlToPdf;
+    private requireUtilities;
+    platformRequest<T>(callerName: string, method: string, path: string, options?: RequestOptions): Promise<T>;
+    platformRequestRaw(callerName: string, method: string, path: string, options?: RequestRawOptions): Promise<Response>;
+    htmlToPdfFetch(callerName: string, path: string, init: RequestInit): Promise<Response>;
+    utilitiesRequest<T>(callerName: string, method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+
+interface Attachment {
+    filename: string;
+    /** Base64-encoded file content. */
+    content: string;
+    content_type: string;
+}
+interface TransactionalMailSendRequest {
+    from: string;
+    to: string[];
+    subject: string;
+    body_html?: string;
+    body_text?: string;
+    reply_to?: string;
+    attachments?: Attachment[];
+}
+interface TransactionalMailSendResponse {
+    message_id: string;
+}
+declare class MailClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    sendTransactional(params: TransactionalMailSendRequest): Promise<TransactionalMailSendResponse>;
+}
+
+interface MailboxSendRequest {
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    body_html?: string;
+    body_text?: string;
+    /** Message ID to reply to. Threads the message correctly. */
+    reply_to_id?: string;
+    attachments?: Attachment[];
+}
+interface MailboxSendResponse {
+    message_id: string;
+}
+interface MailboxAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+}
+interface MailboxMessageSummary {
+    id: string;
+    subject: string;
+    from: string;
+    to: string[];
+    /** First 150 characters of the body, HTML stripped. */
+    preview: string;
+    received_at: string;
+    has_attachments: boolean;
+    is_read: boolean;
+    is_processed: boolean;
+    processed_at: string | null;
+}
+interface MailboxMessagesListResponse {
+    messages: MailboxMessageSummary[];
+    total: number;
+}
+interface MailboxMessageDetail {
+    id: string;
+    subject: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    body_html?: string;
+    body_text?: string;
+    received_at: string;
+    is_read: boolean;
+    is_processed: boolean;
+    processed_at: string | null;
+    attachments: MailboxAttachment[];
+}
+interface MailboxMarkProcessedResponse {
+    ok: true;
+    id: string;
+    already_processed: boolean;
+    processed_at: string;
+}
+interface MailboxConnectorStatus {
+    healthy: boolean;
+    state: 'healthy' | 'unhealthy';
+    /** ISO timestamp of the last state change, or null if never changed. */
+    changed_at: string | null;
+}
+declare class MailboxClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    send(params: MailboxSendRequest): Promise<MailboxSendResponse>;
+    list(limit?: number): Promise<MailboxMessagesListResponse>;
+    get(id: string): Promise<MailboxMessageDetail>;
+    markProcessed(id: string): Promise<MailboxMarkProcessedResponse>;
+    /**
+     * Download a mailbox message attachment as a Buffer.
+     */
+    getAttachment(messageId: string, attachmentId: string): Promise<Buffer>;
+    getConnectorStatus(): Promise<MailboxConnectorStatus>;
+    /**
+     * Dev-only: toggle the mock connector's health state.
+     */
+    setConnectorStatus(healthy: boolean): Promise<MailboxConnectorStatus>;
+}
+
+interface SmsSendRequest {
+    /** Sender phone number in E.164 format. */
+    from: string;
+    /** Recipient phone number in E.164 format. */
+    to: string;
+    /** SMS text content. Max 1600 characters. */
+    body: string;
+}
+interface SmsSendResponse {
+    message_id: string;
+    status: 'queued';
+}
+declare class SmsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    send(params: SmsSendRequest): Promise<SmsSendResponse>;
+}
+
+interface WhatsAppParameter {
+    type: 'text' | 'image' | 'document' | 'video';
+    parameter_name?: string;
+    text?: string;
+    image?: {
+        link: string;
+    };
+    document?: {
+        link: string;
+        filename: string;
+    };
+    video?: {
+        link: string;
+    };
+}
+interface WhatsAppComponent {
+    type: 'header' | 'body' | 'button';
+    sub_type?: 'url' | 'quick_reply';
+    index?: number;
+    parameters: WhatsAppParameter[];
+}
+interface WhatsAppSendRequest {
+    /** Recipient phone number in E.164 format. */
+    to: string;
+    /** Pre-approved WhatsApp template name. */
+    template_name: string;
+    /** BCP 47 language code (e.g. "en", "nl", "fr"). */
+    language_code: string;
+    components?: WhatsAppComponent[];
+}
+interface WhatsAppSendResponse {
+    message_id: string;
+    status: 'queued';
+}
+declare class WhatsAppClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    send(params: WhatsAppSendRequest): Promise<WhatsAppSendResponse>;
+}
+
+interface VoiceTranscribeRequest {
+    /** Base64-encoded audio buffer. */
+    file: string;
+    file_name: string;
+    /** Optional BCP-47 language code (e.g. "en", "nl"). */
+    language_code?: string;
+}
+interface VoiceTranscribeResponse {
+    job_id: string;
+    status: string;
+    text: string;
+}
+declare class VoiceClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    transcribe(params: VoiceTranscribeRequest): Promise<VoiceTranscribeResponse>;
+}
+
+interface FileUploadResponse {
+    key: string;
+    content_type: string;
+    size_bytes: number;
+}
+interface FileListItem {
+    key: string;
+    is_folder: boolean;
+    content_type: string | null;
+    size_bytes: number;
+    created_at: string | null;
+}
+interface FileListResponse {
+    files: FileListItem[];
+    next_cursor: string | null;
+}
+interface PresignedUrlResponse {
+    url: string;
+    expires_in: number;
+}
+type FileUploadBody = Buffer | Uint8Array | ReadableStream | string;
+declare class FilesClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    upload(key: string, file: FileUploadBody, contentType?: string): Promise<FileUploadResponse>;
+    /**
+     * Download a file. Returns the raw Response for streaming.
+     */
+    get(key: string): Promise<Response>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<FileListResponse>;
+    delete(key: string): Promise<{
+        ok: true;
+    }>;
+    deleteMany(prefix: string): Promise<{
+        ok: true;
+        deleted: number;
+    }>;
+    /**
+     * Generate a time-limited download URL for a file.
+     * @param expiresIn TTL in seconds (default 3600, min 60, max 86400)
+     */
+    presignedDownloadUrl(key: string, expiresIn?: number): Promise<PresignedUrlResponse>;
+    /**
+     * Generate a time-limited upload URL for a file.
+     * @param expiresIn TTL in seconds (default 3600, min 60, max 86400)
+     * @param maxSize Max file size in bytes (default 50MB)
+     */
+    presignedUploadUrl(key: string, contentType: string, expiresIn?: number, maxSize?: number): Promise<PresignedUrlResponse>;
+}
+
+type Role = 'user' | 'assistant' | 'system';
+interface InputMessage {
+    role: Role;
+    content: string;
+}
+type Input = string | InputMessage[];
+interface ParseRequest<TSchema extends z.ZodType> {
+    /** Model identifier, e.g. "claude-opus-4-7", "claude-sonnet-4-6". */
+    model: string;
+    input: Input;
+    /** Zod schema describing the structured output shape. */
+    schema: TSchema;
+}
+interface ParseResponse<T> {
+    data: T;
+}
+type StreamEvent<T> = {
+    type: 'partial';
+    data: Partial<T>;
+} | {
+    type: 'complete';
+    data: T;
+} | {
+    type: 'error';
+    message: string;
+};
+declare class AiClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    parse<TSchema extends z.ZodType>(params: ParseRequest<TSchema>): Promise<z.infer<TSchema>>;
+    stream<TSchema extends z.ZodType>(params: ParseRequest<TSchema>): AsyncGenerator<StreamEvent<z.infer<TSchema>>, void, void>;
+}
+
+interface PdfOptions {
+    format?: string;
+    printBackground?: boolean;
+    margin?: {
+        top?: string;
+        right?: string;
+        bottom?: string;
+        left?: string;
+    };
+}
+interface HtmlToPdfBase64Request {
+    /** Base64-encoded HTML content. Provide either `html` or `sourceUrl`. */
+    html?: string;
+    sourceUrl?: string;
+    outputMode: 'base64';
+    options?: PdfOptions;
+}
+interface HtmlToPdfUploadRequest {
+    html?: string;
+    sourceUrl?: string;
+    /** Pre-signed URL the service will PUT the rendered PDF to. */
+    uploadUrl: string;
+    options?: PdfOptions;
+}
+type HtmlToPdfRequest = HtmlToPdfBase64Request | HtmlToPdfUploadRequest;
+interface HtmlToPdfBase64Response {
+    pdf: string;
+}
+interface HtmlToPdfUploadResponse {
+    uploaded: true;
+    bytes: number;
+}
+type HtmlToPdfResponse = HtmlToPdfBase64Response | HtmlToPdfUploadResponse;
+interface QueuedEvent {
+    position: number;
+}
+interface ProcessingEvent {
+    step: string;
+    progress: number;
+}
+interface HtmlToPdfCallbacks {
+    onQueued?: (data: QueuedEvent) => void;
+    onProcessing?: (data: ProcessingEvent) => void;
+}
+declare class HtmlToPdfClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    convert(params: HtmlToPdfBase64Request, callbacks?: HtmlToPdfCallbacks): Promise<HtmlToPdfBase64Response>;
+    convert(params: HtmlToPdfUploadRequest, callbacks?: HtmlToPdfCallbacks): Promise<HtmlToPdfUploadResponse>;
+}
+
+interface MjmlValidationError {
+    line: number;
+    message: string;
+    tagName: string;
+    formattedMessage: string;
+}
+interface MjmlCompileRequest {
+    mjml: string;
+    options?: {
+        minify?: boolean;
+        beautify?: boolean;
+        validationLevel?: 'strict' | 'soft' | 'skip';
+    };
+}
+interface MjmlCompileResponse {
+    html: string;
+    errors: MjmlValidationError[];
+}
+interface LiquidRenderRequest {
+    template: string;
+    data: Record<string, unknown>;
+}
+interface LiquidRenderResponse {
+    result: string;
+}
+interface LiquidVariablesRequest {
+    template: string;
+}
+interface LiquidVariablesResponse {
+    variables: string[];
+}
+interface MarkdownRenderRequest {
+    markdown: string;
+}
+interface MarkdownRenderResponse {
+    html: string;
+}
+interface RenderEmailRequest {
+    mjml: string;
+    data: Record<string, unknown>;
+    options?: {
+        minify?: boolean;
+        beautify?: boolean;
+        validationLevel?: 'strict' | 'soft' | 'skip';
+    };
+}
+interface RenderEmailResponse {
+    html: string;
+    errors: MjmlValidationError[];
+}
+declare class UtilitiesClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    compileMjml(params: MjmlCompileRequest): Promise<MjmlCompileResponse>;
+    renderLiquid(params: LiquidRenderRequest): Promise<LiquidRenderResponse>;
+    extractLiquidVariables(params: LiquidVariablesRequest): Promise<LiquidVariablesResponse>;
+    renderMarkdown(params: MarkdownRenderRequest): Promise<MarkdownRenderResponse>;
+    renderEmail(params: RenderEmailRequest): Promise<RenderEmailResponse>;
+}
+
+interface ErrorResponseBody {
+    error: {
+        code?: string;
+        message: string;
+    };
+}
+declare const CONNECTOR_UNHEALTHY_CODE = "CONNECTOR_UNHEALTHY";
+declare const PLATFORM_NOT_CONFIGURED_CODE = "platform_not_configured";
+declare const HTML_TO_PDF_NOT_CONFIGURED_CODE = "html_to_pdf_not_configured";
+declare const UTILITIES_NOT_CONFIGURED_CODE = "utilities_not_configured";
+declare class UlvioError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly response?: unknown;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        response?: unknown;
+        cause?: unknown;
+    });
+}
+declare function isConnectorUnhealthyError(err: unknown): boolean;
+
+declare class Ulvio {
+    readonly mail: MailClient;
+    readonly mailbox: MailboxClient;
+    readonly sms: SmsClient;
+    readonly whatsapp: WhatsAppClient;
+    readonly voice: VoiceClient;
+    readonly files: FilesClient;
+    readonly ai: AiClient;
+    readonly htmlToPdf: HtmlToPdfClient;
+    readonly utilities: UtilitiesClient;
+    constructor(config?: UlvioConfig);
+}
+
+export { AiClient, type Attachment, CONNECTOR_UNHEALTHY_CODE, type ErrorResponseBody, type FileListItem, type FileListResponse, type FileUploadBody, type FileUploadResponse, FilesClient, HTML_TO_PDF_NOT_CONFIGURED_CODE, type HtmlToPdfBase64Request, type HtmlToPdfBase64Response, type HtmlToPdfCallbacks, HtmlToPdfClient, type HtmlToPdfRequest, type HtmlToPdfResponse, type HtmlToPdfUploadRequest, type HtmlToPdfUploadResponse, type Input, type InputMessage, type LiquidRenderRequest, type LiquidRenderResponse, type LiquidVariablesRequest, type LiquidVariablesResponse, MailClient, type MailboxAttachment, MailboxClient, type MailboxConnectorStatus, type MailboxMarkProcessedResponse, type MailboxMessageDetail, type MailboxMessageSummary, type MailboxMessagesListResponse, type MailboxSendRequest, type MailboxSendResponse, type MarkdownRenderRequest, type MarkdownRenderResponse, type MjmlCompileRequest, type MjmlCompileResponse, type MjmlValidationError, PLATFORM_NOT_CONFIGURED_CODE, type ParseRequest, type ParseResponse, type PdfOptions, type PresignedUrlResponse, type ProcessingEvent, type QueuedEvent, type RenderEmailRequest, type RenderEmailResponse, type Role, SmsClient, type SmsSendRequest, type SmsSendResponse, type StreamEvent, type TransactionalMailSendRequest, type TransactionalMailSendResponse, UTILITIES_NOT_CONFIGURED_CODE, Ulvio, type UlvioConfig, UlvioError, UtilitiesClient, VoiceClient, type VoiceTranscribeRequest, type VoiceTranscribeResponse, WhatsAppClient, type WhatsAppComponent, type WhatsAppParameter, type WhatsAppSendRequest, type WhatsAppSendResponse, isConnectorUnhealthyError };