@kivel.io/sdk 0.0.0-stage → 0.8.0

package/dist/index.js

@@ -0,0 +1,523 @@
+export * from './types.js';
+export class KivelError extends Error {
+    status;
+    requestId;
+    retryAfter;
+    requiredPlan;
+    upgradeUrl;
+    constructor(message, status, requestId, retryAfter, requiredPlan, upgradeUrl) {
+        super(message);
+        this.status = status;
+        this.requestId = requestId;
+        this.retryAfter = retryAfter;
+        this.requiredPlan = requiredPlan;
+        this.upgradeUrl = upgradeUrl;
+        this.name = 'KivelError';
+    }
+}
+export class Kivel {
+    options;
+    baseUrl;
+    fetcher;
+    timeoutMs;
+    constructor(options = {}) {
+        this.options = options;
+        const url = new URL(options.baseUrl ?? 'https://kivel.io');
+        if (!['http:', 'https:'].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.pathname !== '/' ||
+            url.search ||
+            url.hash)
+            throw new Error('baseUrl must be an HTTP(S) origin.');
+        if (url.protocol !== 'https:' &&
+            !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+            throw new Error('Remote API origins must use HTTPS.');
+        this.baseUrl = url.origin;
+        this.fetcher = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? 25000;
+    }
+    async request(method, path, body, resourceToken, headers = {}) {
+        const pathname = path.split('?')[0];
+        if ((!/^\/(?:api|mock)\//.test(path) &&
+            !/^\/ping\/[A-Za-z0-9_-]{32}(?:\/fail)?$/.test(path)) ||
+            /[\\#\x00-\x20]/.test(path) ||
+            pathname.split('/').some((part) => {
+                try {
+                    return ['.', '..'].includes(decodeURIComponent(part)) || /%2f|%5c/i.test(part);
+                }
+                catch {
+                    return true;
+                }
+            }))
+            throw new Error('Use a relative /api/ or /mock/ path without traversal.');
+        const requestHeaders = new Headers(headers);
+        requestHeaders.set('Accept', 'application/json');
+        if (this.options.apiKey)
+            requestHeaders.set('Authorization', `Bearer ${this.options.apiKey}`);
+        if (resourceToken)
+            requestHeaders.set(path.startsWith('/mock/') ? 'X-Access-Token' : 'X-Resource-Token', resourceToken);
+        const binary = body instanceof Uint8Array || body instanceof ArrayBuffer;
+        if (body !== undefined)
+            requestHeaders.set('Content-Type', binary ? 'application/octet-stream' : 'application/json');
+        const response = await this.fetcher(`${this.baseUrl}${path}`, {
+            method,
+            headers: requestHeaders,
+            ...(body !== undefined
+                ? { body: binary ? body : JSON.stringify(body) }
+                : {}),
+            redirect: 'error',
+            credentials: 'omit',
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (response.status === 204 ||
+            response.status === 304 ||
+            (method.toUpperCase() === 'HEAD' && response.ok))
+            return undefined;
+        const text = await response.text();
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            if (response.ok && path.startsWith('/mock/'))
+                return text;
+            throw new KivelError('The server returned an invalid response.', response.status, response.headers.get('x-request-id') ?? undefined);
+        }
+        if (!response.ok) {
+            const message = value &&
+                typeof value === 'object' &&
+                'error' in value &&
+                typeof value.error === 'string'
+                ? value.error
+                : `Request failed (${response.status}).`;
+            throw new KivelError(message, response.status, response.headers.get('x-request-id') ?? undefined, Number(response.headers.get('retry-after')) || undefined, value &&
+                typeof value === 'object' &&
+                'requiredPlan' in value &&
+                typeof value.requiredPlan === 'string'
+                ? value.requiredPlan
+                : undefined, value &&
+                typeof value === 'object' &&
+                'upgradeUrl' in value &&
+                typeof value.upgradeUrl === 'string'
+                ? value.upgradeUrl
+                : undefined);
+        }
+        return value;
+    }
+    tools() {
+        return this.request('GET', '/api/tools');
+    }
+    tool(id) {
+        return this.request('GET', `/api/tools/${encodeURIComponent(id)}`);
+    }
+    run(toolId, input = '', options = {}, file) {
+        return this.request('POST', `/api/tools/${encodeURIComponent(toolId)}/run`, {
+            input,
+            options,
+            ...(file ? { file } : {}),
+        });
+    }
+    plans() {
+        return this.request('GET', '/api/plans');
+    }
+    activity() {
+        return this.request('GET', '/api/account/activity');
+    }
+    startLogin(name, client) {
+        return this.request('POST', '/api/agents/login', { name, client });
+    }
+    finishLogin(deviceCode) {
+        return this.request('POST', '/api/agents/token', { deviceCode });
+    }
+    startTrial(name, humanEmail, client) {
+        return this.request('POST', '/api/agents/trial', { name, humanEmail, client });
+    }
+    agents() {
+        return this.request('GET', '/api/agents');
+    }
+    /** Only for accounts your human asked you to create or operate. */
+    addAuthenticator(input) {
+        return this.request('POST', '/api/authenticators', input);
+    }
+    listAuthenticators() {
+        return this.request('GET', '/api/authenticators');
+    }
+    getTotpCode(id) {
+        return this.request('GET', `/api/authenticators/${encodeURIComponent(id)}/code`);
+    }
+    renameAuthenticator(id, name) {
+        return this.request('PATCH', `/api/authenticators/${encodeURIComponent(id)}`, { name });
+    }
+    deleteAuthenticator(id) {
+        return this.request('DELETE', `/api/authenticators/${encodeURIComponent(id)}`);
+    }
+    getEmailAttachment(id, messageId, attachmentId) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`);
+    }
+    async downloadEmailAttachment(id, messageId, attachmentId) {
+        const link = await this.getEmailAttachment(id, messageId, attachmentId);
+        const url = new URL(link.downloadUrl);
+        if (url.origin !== new URL(this.baseUrl).origin ||
+            !url.pathname.startsWith('/api/email-inboxes/'))
+            throw new Error('Invalid attachment download URL.');
+        const response = await this.fetcher(url, {
+            redirect: 'error',
+            credentials: 'omit',
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok)
+            throw new KivelError('Attachment link expired or unavailable.', response.status, response.headers.get('x-request-id') ?? undefined);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    createTestWallet(input) {
+        return this.request('POST', '/api/test-wallets', input);
+    }
+    createTestPaywall(input) {
+        return this.request('POST', '/api/test-paywalls', input);
+    }
+    createTestCheckout(input) {
+        return this.request('POST', '/api/test-checkouts', input);
+    }
+    testPayments(kind) {
+        return this.request('GET', `/api/test-${kind}`);
+    }
+    testPayment(kind, id) {
+        return this.request('GET', `/api/test-${kind}/${encodeURIComponent(id)}`);
+    }
+    updateTestPayment(kind, id, input) {
+        return this.request('PATCH', `/api/test-${kind}/${encodeURIComponent(id)}`, input);
+    }
+    deleteTestPayment(kind, id) {
+        return this.request('DELETE', `/api/test-${kind}/${encodeURIComponent(id)}`);
+    }
+    walletBalance(id) {
+        return this.testPayment('wallets', id);
+    }
+    topUpTestWallet(id, amount) {
+        return this.request('POST', `/api/test-wallets/${encodeURIComponent(id)}/top-up`, { amount });
+    }
+    walletPay(id, input) {
+        return this.request('POST', `/api/test-wallets/${encodeURIComponent(id)}/pay`, input);
+    }
+    listWalletTransactions(id, options = {}) {
+        const query = new URLSearchParams();
+        if (options.cursor)
+            query.set('cursor', options.cursor);
+        if (options.limit !== undefined)
+            query.set('limit', String(options.limit));
+        return this.request('GET', `/api/test-wallets/${encodeURIComponent(id)}/transactions?${query}`);
+    }
+    completeTestCheckout(id, input) {
+        return this.request('POST', `/api/test-checkouts/${encodeURIComponent(id)}/complete`, input);
+    }
+    confirmTestCheckout(id, confirmationToken) {
+        return this.request('POST', `/api/test-checkouts/${encodeURIComponent(id)}/confirm`, { confirmationToken });
+    }
+    saveCredential(input) {
+        return this.request('POST', '/api/credentials', input);
+    }
+    credentials() {
+        return this.request('GET', '/api/credentials');
+    }
+    credential(id) {
+        return this.request('GET', `/api/credentials/${encodeURIComponent(id)}`);
+    }
+    updateCredential(id, input) {
+        return this.request('PATCH', `/api/credentials/${encodeURIComponent(id)}`, input);
+    }
+    deleteCredential(id) {
+        return this.request('DELETE', `/api/credentials/${encodeURIComponent(id)}`);
+    }
+    revealCredential(id, approvalId) {
+        return this.request('POST', `/api/credentials/${encodeURIComponent(id)}/reveal`, approvalId ? { approvalId } : {});
+    }
+    generatePassword(length = 24) {
+        return this.request('POST', '/api/passwords/generate', { length });
+    }
+    createEmailInbox(settings = {}) {
+        return this.request('POST', '/api/email-inboxes', settings);
+    }
+    emailInboxes() {
+        return this.request('GET', '/api/email-inboxes');
+    }
+    clearEmails(id, token) {
+        return this.request('DELETE', `/api/email-inboxes/${encodeURIComponent(id)}/messages`, undefined, token);
+    }
+    sendEmail(id, input) {
+        const { idempotencyKey, ...body } = input;
+        return this.request('POST', `/api/email-inboxes/${encodeURIComponent(id)}/send`, body, undefined, { 'Idempotency-Key': idempotencyKey });
+    }
+    emailThreads(id, settings = {}) {
+        const query = new URLSearchParams();
+        if (settings.cursor)
+            query.set('cursor', settings.cursor);
+        if (settings.limit !== undefined)
+            query.set('limit', String(settings.limit));
+        const path = id
+            ? `/api/email-inboxes/${encodeURIComponent(id)}/threads`
+            : '/api/email-threads';
+        return this.request('GET', path + (query.size ? `?${query}` : ''));
+    }
+    emailThread(id, threadId) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/threads/${encodeURIComponent(threadId)}`);
+    }
+    createEmailDraft(id, content) {
+        return this.request('POST', `/api/email-inboxes/${encodeURIComponent(id)}/drafts`, content);
+    }
+    emailDrafts(id) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/drafts`);
+    }
+    emailDraft(id) {
+        return this.request('GET', `/api/email-drafts/${encodeURIComponent(id)}`);
+    }
+    submitEmailDraft(id, settings = {}) {
+        return this.request('POST', `/api/email-drafts/${encodeURIComponent(id)}/send`, settings);
+    }
+    deleteEmailDraft(id) {
+        return this.request('DELETE', `/api/email-drafts/${encodeURIComponent(id)}`);
+    }
+    emailInboxRules(id) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/rules`);
+    }
+    waitForEvent(sources, timeoutSeconds = 20) {
+        return this.request('POST', '/api/events/wait', { sources, timeoutSeconds: this.waitTimeout(timeoutSeconds) });
+    }
+    emailForwarding(id, url, token) {
+        return this.request('PUT', `/api/email-inboxes/${encodeURIComponent(id)}/forwarding`, { url }, token);
+    }
+    emailInbox(id, token) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}`, undefined, token);
+    }
+    emails(id, token) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/messages`, undefined, token);
+    }
+    waitForEmail(id, options = {}) {
+        return this.request('GET', `/api/email-inboxes/${encodeURIComponent(id)}/wait${this.waitQuery(options)}`, undefined, options.token);
+    }
+    memorySet(namespace, key, value, ttlSeconds) {
+        return this.request('PUT', memoryPath(namespace, key), {
+            value,
+            ttlSeconds,
+        });
+    }
+    memoryGet(namespace, key) {
+        return this.request('GET', memoryPath(namespace, key));
+    }
+    memoryList(namespace, prefix = '') {
+        return this.request('GET', `${memoryPath(namespace)}${query({ prefix })}`);
+    }
+    memoryDelete(namespace, key) {
+        return this.request('DELETE', memoryPath(namespace, key));
+    }
+    availablePhoneNumbers(areaCode) {
+        return this.request('GET', `/api/phone-numbers/available${query({ areaCode })}`);
+    }
+    createPhoneNumber(number, idempotencyKey) {
+        return this.request('POST', '/api/phone-numbers', { number }, undefined, { 'Idempotency-Key': idempotencyKey });
+    }
+    listPhoneNumbers() {
+        return this.request('GET', '/api/phone-numbers');
+    }
+    releasePhoneNumber(id) {
+        return this.request('DELETE', `/api/phone-numbers/${encodeURIComponent(id)}`);
+    }
+    listSms(id) {
+        return this.request('GET', `/api/phone-numbers/${encodeURIComponent(id)}/sms`);
+    }
+    waitForSms(id, options = {}) {
+        return this.request('GET', `/api/phone-numbers/${encodeURIComponent(id)}/wait${this.waitQuery(options)}`);
+    }
+    createSmtpInbox(settings = {}) {
+        return this.request('POST', `/api/smtp-inboxes${query(settings)}`);
+    }
+    smtpInbox(id) {
+        return this.request('GET', `/api/smtp-inboxes/${encodeURIComponent(id)}`);
+    }
+    rotateSmtpPassword(id) {
+        return this.request('POST', `/api/smtp-inboxes/${encodeURIComponent(id)}/rotate`);
+    }
+    createScheduledJob(config, settings = {}) {
+        return this.request('POST', `/api/scheduled-jobs${query(settings)}`, config);
+    }
+    scheduledJobs() {
+        return this.request('GET', '/api/scheduled-jobs');
+    }
+    scheduledJob(id) {
+        return this.request('GET', `/api/scheduled-jobs/${encodeURIComponent(id)}`);
+    }
+    cancelScheduledJob(id) {
+        return this.request('DELETE', `/api/scheduled-jobs/${encodeURIComponent(id)}`);
+    }
+    createStatusPage(config, settings = {}) {
+        return this.request('POST', `/api/status-pages${query(settings)}`, config);
+    }
+    updateStatusPage(id, config) {
+        return this.request('PUT', `/api/status-pages/${encodeURIComponent(id)}`, config);
+    }
+    acceptDnsChanges(id) {
+        return this.request('POST', `/api/monitors/${encodeURIComponent(id)}/accept-dns`);
+    }
+    createMonitor(settings) {
+        return this.request('POST', '/api/monitors', settings);
+    }
+    monitors() {
+        return this.request('GET', '/api/monitors');
+    }
+    monitor(id) {
+        return this.request('GET', `/api/monitors/${encodeURIComponent(id)}`);
+    }
+    pingMonitor(token, failed = false) {
+        if (!/^[A-Za-z0-9_-]{32}$/.test(token))
+            throw new Error('Provide the token from the monitor pingUrl.');
+        return this.request('POST', `/ping/${token}${failed ? '/fail' : ''}`);
+    }
+    pauseMonitor(id, paused = true) {
+        return this.request('PATCH', `/api/monitors/${encodeURIComponent(id)}`, { paused });
+    }
+    deleteMonitor(id) {
+        return this.request('DELETE', `/api/monitors/${encodeURIComponent(id)}`);
+    }
+    askHuman(input) {
+        return this.request('POST', '/api/approvals', input);
+    }
+    approvals(pendingOnly = false) {
+        return this.request('GET', `/api/approvals${pendingOnly ? '?status=pending' : ''}`);
+    }
+    approval(id) {
+        return this.request('GET', `/api/approvals/${encodeURIComponent(id)}`);
+    }
+    waitForApproval(id, timeoutSeconds) {
+        return this.request('GET', `/api/approvals/${encodeURIComponent(id)}/wait${this.waitQuery({ timeoutSeconds })}`);
+    }
+    inspectResource(kind, id, token) {
+        return this.request('GET', `/api/${kind}/${encodeURIComponent(id)}`, undefined, token);
+    }
+    updateMock(id, config, token) {
+        return this.request('PUT', `/api/mocks/${encodeURIComponent(id)}`, config, token);
+    }
+    resetMock(id, token) {
+        return this.request('POST', `/api/mocks/${encodeURIComponent(id)}/reset`, {}, token);
+    }
+    mockCalls(id, token) {
+        return this.request('GET', `/api/mocks/${encodeURIComponent(id)}/calls`, undefined, token);
+    }
+    setInboxForward(id, url, token) {
+        return this.request(url === null ? 'DELETE' : 'PUT', `/api/inboxes/${encodeURIComponent(id)}/forward`, url === null ? undefined : { url }, token);
+    }
+    inboxDeliveries(id, token) {
+        return this.request('GET', `/api/inboxes/${encodeURIComponent(id)}/deliveries`, undefined, token);
+    }
+    waitTimeout(timeoutSeconds) {
+        const ceiling = Math.max(1, Math.floor(this.timeoutMs / 1000) - 5);
+        return Math.min(timeoutSeconds ?? 20, ceiling, 30);
+    }
+    waitQuery(options) {
+        return query({
+            after: options.after,
+            timeoutSeconds: this.waitTimeout(options.timeoutSeconds),
+        });
+    }
+    usage() {
+        return this.request('GET', '/api/usage');
+    }
+    resources() {
+        return this.request('GET', '/api/account/resources');
+    }
+    /** Senders can POST to webhookUrl without credentials by default. Inspection stays private.
+     * Set visibility to private to require X-Access-Token on incoming webhooks. */
+    createInbox(settings = {}) {
+        return this.request('POST', `/api/inboxes${creationQuery({ ...settings, visibility: settings.visibility ?? 'public' })}`);
+    }
+    inspectInbox(id, token) {
+        return this.request('GET', `/api/inboxes/${encodeURIComponent(id)}/requests`, undefined, token);
+    }
+    /**
+     * Long-polls until the inbox captures a request newer than `after` (any request when omitted).
+     * Resolves with `timedOut: true` when nothing arrives; call again to keep waiting.
+     */
+    waitForRequests(id, options = {}) {
+        // Stay inside the client timeout so the server answers before the request is aborted.
+        const query = new URLSearchParams({
+            timeoutSeconds: String(this.waitTimeout(options.timeoutSeconds)),
+            ...(options.after ? { after: options.after } : {}),
+        });
+        return this.request('GET', `/api/inboxes/${encodeURIComponent(id)}/wait?${query}`, undefined, options.token);
+    }
+    setInboxResponse(id, response, token) {
+        if (response !== null &&
+            (!response || typeof response !== 'object' || Array.isArray(response)))
+            throw new Error('Provide response settings as an object, or null to reset.');
+        return this.request(response === null ? 'DELETE' : 'PUT', `/api/inboxes/${encodeURIComponent(id)}/response`, response ?? undefined, token);
+    }
+    createOAuthProvider(config, settings = {}) {
+        return this.request('POST', `/api/oauth-providers${creationQuery(settings)}`, config);
+    }
+    oauthProvider(id) {
+        return this.request('GET', `/api/oauth-providers/${encodeURIComponent(id)}`);
+    }
+    oauthProviders() {
+        return this.request('GET', '/api/oauth-providers');
+    }
+    updateOAuthProvider(id, config) {
+        return this.request('PUT', `/api/oauth-providers/${encodeURIComponent(id)}`, config);
+    }
+    deleteOAuthProvider(id) {
+        return this.request('DELETE', `/api/oauth-providers/${encodeURIComponent(id)}`);
+    }
+    createMock(config, settings = {}) {
+        return this.request('POST', `/api/mocks${creationQuery(settings)}`, config);
+    }
+    createMcpServer(config, settings = {}) {
+        return this.request('POST', `/api/mcp-servers${creationQuery(settings)}`, config);
+    }
+    upload(name, data, settings = {}) {
+        return this.request('POST', `/api/files${creationQuery(settings)}`, data, undefined, { 'X-File-Name': encodeURIComponent(name) });
+    }
+    sharing(kind, id, visibility, token) {
+        return this.request('POST', `/api/${kind}/${encodeURIComponent(id)}/sharing`, { visibility }, token);
+    }
+    async downloadFile(id, accessToken) {
+        if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(id))
+            throw new Error('Provide a file UUID.');
+        const headers = {};
+        if (accessToken)
+            headers['X-Access-Token'] = accessToken;
+        if (this.options.apiKey)
+            headers.Authorization = `Bearer ${this.options.apiKey}`;
+        const response = await this.fetcher(`${this.baseUrl}/files/${id}`, {
+            method: 'GET',
+            headers,
+            redirect: 'error',
+            credentials: 'omit',
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok)
+            throw new KivelError('File unavailable or access denied.', response.status, response.headers.get('x-request-id') ?? undefined);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    remove(kind, id, token) {
+        return this.request('DELETE', `/api/${kind}/${encodeURIComponent(id)}`, undefined, token);
+    }
+    renew(kind, id, settings = {}, token) {
+        return this.request('POST', `/api/${kind}/${encodeURIComponent(id)}/renew`, settings, token);
+    }
+}
+function query(settings) {
+    const params = new URLSearchParams(Object.entries(settings)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, String(value)]));
+    return params.size ? `?${params}` : '';
+}
+function creationQuery(settings) {
+    return query({ ...settings, visibility: settings.visibility ?? 'private' });
+}
+function memoryPath(namespace, key) {
+    if (!/^[a-zA-Z0-9_.:-]{1,64}$/.test(namespace) || ['.', '..'].includes(namespace))
+        throw new Error('Provide a valid memory namespace.');
+    if (key !== undefined &&
+        (!/^[a-zA-Z0-9_./:-]{1,200}$/.test(key) ||
+            key.split('/').some((part) => ['.', '..'].includes(part))))
+        throw new Error('Provide a valid memory key without traversal.');
+    return `/api/memory/${encodeURIComponent(namespace)}${key === undefined ? '' : '/' + key.split('/').map(encodeURIComponent).join('/')}`;
+}