@sensigo/realm 0.1.0

package/dist/adapters/gorgias-adapter.js

@@ -0,0 +1,300 @@
+// GorgiasAdapter — communicates with the Gorgias REST API.
+import { WorkflowError } from '../types/workflow-error.js';
+import { parseRetryAfterHeader } from './adapter-utils.js';
+/**
+ * Intentionally minimal — strips tags and decodes five common HTML entities.
+ * Sufficient for Gorgias plain-text note bodies.
+ */
+function stripHtmlTags(html) {
+    return html
+        .replace(/<[^>]*>/g, '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#039;/g, "'")
+        .trim();
+}
+/**
+ * GorgiasAdapter communicates with the Gorgias REST API.
+ *
+ * Supported operations:
+ *   fetch('get_ticket', { ticket_id })                          — GET  /tickets/{ticket_id}
+ *   fetch('get_messages', { ticket_id, limit? })               — GET  /messages?ticket_id={ticket_id}&...
+ *   create('post_internal_note', { ticket_id, body_html })     — POST /tickets/{ticket_id}/messages
+ */
+export class GorgiasAdapter {
+    id;
+    defaultRetryAfterSeconds = 60;
+    baseUrl;
+    authHeader;
+    constructor(id, config) {
+        // Validate domain — parse and verify the hostname matches to reject values with
+        // path segments or query strings (e.g. 'evil.com/api?q=').
+        let domainValid = false;
+        try {
+            const testUrl = new URL(`https://${config.domain}.gorgias.com`);
+            domainValid = testUrl.hostname === `${config.domain}.gorgias.com`;
+        }
+        catch {
+            // URL constructor threw — invalid
+        }
+        if (!domainValid) {
+            throw new Error('GorgiasAdapter: invalid domain');
+        }
+        this.id = id;
+        this.baseUrl = config.base_url ?? `https://${config.domain}.gorgias.com/api`;
+        this.authHeader = 'Basic ' + Buffer.from(config.auth.token).toString('base64');
+    }
+    checkAborted(signal) {
+        if (signal?.aborted === true) {
+            throw new WorkflowError('Adapter request aborted', {
+                code: 'STEP_ABORTED',
+                category: 'ENGINE',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+    }
+    buildHeaders() {
+        return {
+            Authorization: this.authHeader,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+    }
+    async executeRequest(method, url, operation, body, signal) {
+        const fetchOptions = method === 'GET'
+            ? { method, headers: this.buildHeaders(), signal: signal ?? null }
+            : {
+                method,
+                headers: this.buildHeaders(),
+                body: JSON.stringify(body),
+                signal: signal ?? null,
+            };
+        let response;
+        try {
+            response = await fetch(url, fetchOptions);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new WorkflowError('Adapter request aborted', {
+                    code: 'STEP_ABORTED',
+                    category: 'ENGINE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new WorkflowError(message, {
+                code: 'NETWORK_UNREACHABLE',
+                category: 'NETWORK',
+                agentAction: 'wait_for_human',
+                retryable: true,
+            });
+        }
+        if (!response.ok) {
+            await this.throwHttpError(response, operation);
+        }
+        const json = await response.json();
+        return { status: response.status, data: json };
+    }
+    async throwHttpError(response, operation) {
+        // Read body as text first — avoids "body already consumed" if JSON.parse fails.
+        const rawText = await response.text();
+        let body;
+        try {
+            body = JSON.parse(rawText);
+        }
+        catch {
+            body = rawText;
+        }
+        const status = response.status;
+        const details = { status, operation, body };
+        if (status === 429) {
+            const retryAfterFromHeader = parseRetryAfterHeader(response.headers.get('Retry-After'));
+            throw new WorkflowError('Rate limited by Gorgias API', {
+                code: 'SERVICE_RATE_LIMITED',
+                category: 'SERVICE',
+                agentAction: 'wait_and_proceed',
+                retryable: true,
+                ...(retryAfterFromHeader !== undefined ? { retry_after: retryAfterFromHeader } : {}),
+                details,
+            });
+        }
+        if (status === 401) {
+            throw new WorkflowError('Gorgias authentication failed — check email and API key', {
+                code: 'SERVICE_AUTH_FAILED',
+                category: 'SERVICE',
+                agentAction: 'stop',
+                retryable: false,
+                details,
+            });
+        }
+        if (status === 403) {
+            const message403 = operation === 'get_ticket'
+                ? 'Account lacks permission to read Gorgias tickets'
+                : operation === 'get_messages'
+                    ? 'Account lacks permission to read Gorgias ticket messages'
+                    : operation === 'post_internal_note'
+                        ? 'Account lacks permission to create Gorgias messages'
+                        : 'Account lacks permission for this Gorgias operation';
+            throw new WorkflowError(message403, {
+                code: 'SERVICE_HTTP_4XX',
+                category: 'SERVICE',
+                agentAction: 'stop',
+                retryable: false,
+                details,
+            });
+        }
+        if (status === 404) {
+            throw new WorkflowError('Gorgias resource not found', {
+                code: 'SERVICE_HTTP_4XX',
+                category: 'SERVICE',
+                agentAction: 'stop',
+                retryable: false,
+                details,
+            });
+        }
+        if (status >= 400 && status < 500) {
+            throw new WorkflowError(`HTTP ${status}: ${response.statusText}`, {
+                code: 'SERVICE_HTTP_4XX',
+                category: 'SERVICE',
+                agentAction: 'stop',
+                retryable: false,
+                details,
+            });
+        }
+        // 5xx
+        throw new WorkflowError(`Gorgias server error (HTTP ${status})`, {
+            code: 'SERVICE_HTTP_5XX',
+            category: 'SERVICE',
+            agentAction: 'report_to_user',
+            retryable: true,
+            details,
+        });
+    }
+    validateTicketId(params) {
+        const ticketId = params['ticket_id'];
+        if (typeof ticketId !== 'number' || !Number.isInteger(ticketId) || ticketId <= 0) {
+            throw new WorkflowError('GorgiasAdapter: ticket_id must be a positive integer', {
+                code: 'ADAPTER_VALIDATION_FAILED',
+                category: 'ENGINE',
+                agentAction: 'provide_input',
+                retryable: false,
+                details: { received: ticketId },
+            });
+        }
+        return ticketId;
+    }
+    normalize(msg) {
+        const body = msg.body_text ?? stripHtmlTags(msg.body_html ?? '') ?? '';
+        return {
+            id: msg.id,
+            from_agent: msg.from_agent,
+            public: msg.public,
+            channel: msg.channel,
+            body,
+            created_datetime: msg.created_datetime,
+        };
+    }
+    async fetch(operation, params, _config, signal) {
+        // config.auth is ignored — auth is set at construction time
+        if (operation === 'get_ticket') {
+            const ticketId = this.validateTicketId(params);
+            this.checkAborted(signal);
+            return this.executeRequest('GET', `${this.baseUrl}/tickets/${ticketId}`, 'get_ticket', undefined, signal);
+        }
+        if (operation === 'get_messages') {
+            const ticketId = this.validateTicketId(params);
+            const userLimit = typeof params['limit'] === 'number' && params['limit'] > 0 ? params['limit'] : 30;
+            const effectiveLimit = Math.min(userLimit, 200);
+            const PAGE_SIZE = 100;
+            const accumulated = [];
+            let cursor = undefined;
+            let truncated = false;
+            for (;;) {
+                this.checkAborted(signal);
+                const url = `${this.baseUrl}/messages?ticket_id=${ticketId}&limit=${PAGE_SIZE}&order_by=created_datetime:asc` +
+                    (cursor !== undefined ? `&cursor=${cursor}` : '');
+                const response = await this.executeRequest('GET', url, 'get_messages', undefined, signal);
+                const json = response.data;
+                for (const message of json.data) {
+                    if (accumulated.length < effectiveLimit) {
+                        accumulated.push(this.normalize(message));
+                    }
+                }
+                const nextCursor = json.meta.next_cursor ?? null;
+                if (nextCursor === null) {
+                    truncated = false;
+                    break;
+                }
+                if (accumulated.length >= effectiveLimit) {
+                    truncated = true;
+                    break;
+                }
+                cursor = nextCursor;
+            }
+            return { status: 200, data: { messages: accumulated, truncated } };
+        }
+        throw new WorkflowError(`GorgiasAdapter: unsupported fetch operation '${operation}'`, {
+            code: 'ADAPTER_OP_UNSUPPORTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { operation },
+        });
+    }
+    async create(operation, params, _config, signal) {
+        // config.auth is ignored — auth is set at construction time
+        if (operation === 'post_internal_note') {
+            const ticketId = this.validateTicketId(params);
+            if (typeof params['body_html'] !== 'string') {
+                throw new WorkflowError('GorgiasAdapter: body_html must be a string', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                    details: { received: params['body_html'] },
+                });
+            }
+            this.checkAborted(signal);
+            const requestBody = {
+                channel: 'note',
+                public: false,
+                from_agent: true,
+                body_html: params['body_html'],
+            };
+            const response = await this.executeRequest('POST', `${this.baseUrl}/tickets/${ticketId}/messages`, 'post_internal_note', requestBody, signal);
+            const json = response.data;
+            const noteId = json.id;
+            if (typeof noteId !== 'number') {
+                throw new WorkflowError('GorgiasAdapter: unexpected response shape from post_internal_note', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'stop',
+                    retryable: false,
+                    details: { received: json },
+                });
+            }
+            return { status: 201, data: { ok: true, note_id: noteId } };
+        }
+        throw new WorkflowError(`GorgiasAdapter: unsupported create operation '${operation}'`, {
+            code: 'ADAPTER_OP_UNSUPPORTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { operation },
+        });
+    }
+    async update(operation, _params, _config, _signal) {
+        throw new WorkflowError(`GorgiasAdapter: update is not supported (operation: '${operation}')`, {
+            code: 'ADAPTER_OP_UNSUPPORTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { operation },
+        });
+    }
+}
+//# sourceMappingURL=gorgias-adapter.js.map

package/dist/adapters/gorgias-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gorgias-adapter.js","sourceRoot":"","sources":["../../src/adapters/gorgias-adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/http-adapter.d.ts

@@ -0,0 +1,28 @@
+import type { ServiceAdapter, ServiceResponse } from '../extensions/service-adapter.js';
+export interface HttpAdapterConfig {
+    base_url: string;
+    headers?: Record<string, string>;
+    auth?: {
+        type: 'bearer' | 'basic' | 'header';
+        token?: string;
+        header_name?: string;
+    };
+}
+/**
+ * GenericHttpAdapter makes HTTP requests to any REST API.
+ * Method mapping:
+ *   fetch()  → GET  {base_url}/{operation}?{params as query string}
+ *   create() → POST {base_url}/{operation} with JSON body
+ *   update() → PATCH {base_url}/{operation} with JSON body
+ */
+export declare class GenericHttpAdapter implements ServiceAdapter {
+    readonly id: string;
+    private readonly config;
+    constructor(id: string, config: HttpAdapterConfig);
+    private buildAuthHeaders;
+    private request;
+    fetch(operation: string, params: Record<string, unknown>, config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    create(operation: string, params: Record<string, unknown>, config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    update(operation: string, params: Record<string, unknown>, config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+}
+//# sourceMappingURL=http-adapter.d.ts.map

package/dist/adapters/http-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/http-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;QACpC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,cAAc;aAErC,EAAE,EAAE,MAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADP,EAAE,EAAE,MAAM,EACT,MAAM,EAAE,iBAAiB;IAG5C,OAAO,CAAC,gBAAgB;YAcV,OAAO;IAqErB,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAI3B,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAI3B,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;CAG5B"}

package/dist/adapters/http-adapter.js

@@ -0,0 +1,97 @@
+// GenericHttpAdapter — makes HTTP requests to any REST API using Node 24 native fetch.
+import { WorkflowError } from '../types/workflow-error.js';
+/**
+ * GenericHttpAdapter makes HTTP requests to any REST API.
+ * Method mapping:
+ *   fetch()  → GET  {base_url}/{operation}?{params as query string}
+ *   create() → POST {base_url}/{operation} with JSON body
+ *   update() → PATCH {base_url}/{operation} with JSON body
+ */
+export class GenericHttpAdapter {
+    id;
+    config;
+    constructor(id, config) {
+        this.id = id;
+        this.config = config;
+    }
+    buildAuthHeaders(auth) {
+        if (auth === undefined)
+            return {};
+        const token = auth.token ?? '';
+        if (auth.type === 'bearer') {
+            return { Authorization: `Bearer ${token}` };
+        }
+        if (auth.type === 'basic') {
+            return { Authorization: `Basic ${Buffer.from(token).toString('base64')}` };
+        }
+        // header type
+        const headerName = auth.header_name ?? 'X-Auth-Token';
+        return { [headerName]: token };
+    }
+    async request(method, operation, params, callConfig, signal) {
+        // Only per-call headers can be merged — base_url and auth are constructor-time
+        // security boundaries that callers must not override.
+        const callHeaders = callConfig['headers'] ?? {};
+        const authHeaders = this.buildAuthHeaders(this.config.auth);
+        const baseHeaders = {
+            ...(this.config.headers ?? {}),
+            ...callHeaders,
+            ...authHeaders,
+        };
+        const url = method === 'GET'
+            ? `${this.config.base_url}/${operation}?${new URLSearchParams(params).toString()}`
+            : `${this.config.base_url}/${operation}`;
+        const fetchOptions = method === 'GET'
+            ? { method, headers: baseHeaders, signal: signal ?? null }
+            : {
+                method,
+                headers: { ...baseHeaders, 'Content-Type': 'application/json' },
+                body: JSON.stringify(params),
+                signal: signal ?? null,
+            };
+        let response;
+        try {
+            response = await fetch(url, fetchOptions);
+        }
+        catch (err) {
+            // AbortError means the engine cancelled this request (e.g. step timeout).
+            // Do not categorize as a network failure — the engine already recorded the reason.
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new WorkflowError(`Adapter request aborted`, {
+                    code: 'STEP_ABORTED',
+                    category: 'ENGINE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new WorkflowError(message, {
+                code: 'NETWORK_UNREACHABLE',
+                category: 'NETWORK',
+                agentAction: 'wait_for_human',
+                retryable: true,
+            });
+        }
+        if (!response.ok) {
+            const status = response.status;
+            throw new WorkflowError(`HTTP ${status}: ${response.statusText}`, {
+                code: status >= 500 ? 'SERVICE_HTTP_5XX' : 'SERVICE_HTTP_4XX',
+                category: 'SERVICE',
+                agentAction: status >= 500 ? 'wait_for_human' : 'report_to_user',
+                retryable: status >= 500,
+            });
+        }
+        const data = await response.json();
+        return { status: response.status, data };
+    }
+    fetch(operation, params, config, signal) {
+        return this.request('GET', operation, params, config, signal);
+    }
+    create(operation, params, config, signal) {
+        return this.request('POST', operation, params, config, signal);
+    }
+    update(operation, params, config, signal) {
+        return this.request('PATCH', operation, params, config, signal);
+    }
+}
+//# sourceMappingURL=http-adapter.js.map

package/dist/adapters/http-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-adapter.js","sourceRoot":"","sources":["../../src/adapters/http-adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/mock-adapter.d.ts

@@ -0,0 +1,16 @@
+import type { ServiceAdapter, ServiceResponse } from '../extensions/service-adapter.js';
+/**
+ * MockAdapter returns pre-configured responses for named operations.
+ * All three methods (fetch, create, update) look up the same responses map.
+ * If an operation is not found, throws WorkflowError(ENGINE_ADAPTER_FAILED).
+ */
+export declare class MockAdapter implements ServiceAdapter {
+    readonly id: string;
+    private readonly responses;
+    constructor(id: string, responses: Record<string, ServiceResponse>);
+    private resolve;
+    fetch(operation: string, _params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    create(operation: string, _params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    update(operation: string, _params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+}
+//# sourceMappingURL=mock-adapter.d.ts.map

package/dist/adapters/mock-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/mock-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExF;;;;GAIG;AACH,qBAAa,WAAY,YAAW,cAAc;aAE9B,EAAE,EAAE,MAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADV,EAAE,EAAE,MAAM,EACT,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAG7D,OAAO,CAAC,OAAO;IAaT,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAYrB,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAYrB,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;CAW5B"}

package/dist/adapters/mock-adapter.js

@@ -0,0 +1,61 @@
+// MockAdapter — returns pre-configured responses for named operations.
+import { WorkflowError } from '../types/workflow-error.js';
+/**
+ * MockAdapter returns pre-configured responses for named operations.
+ * All three methods (fetch, create, update) look up the same responses map.
+ * If an operation is not found, throws WorkflowError(ENGINE_ADAPTER_FAILED).
+ */
+export class MockAdapter {
+    id;
+    responses;
+    constructor(id, responses) {
+        this.id = id;
+        this.responses = responses;
+    }
+    resolve(operation) {
+        const response = this.responses[operation];
+        if (response === undefined) {
+            throw new WorkflowError(`MockAdapter: unknown operation: ${operation}`, {
+                code: 'ENGINE_ADAPTER_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        }
+        return response;
+    }
+    async fetch(operation, _params, _config, signal) {
+        if (signal?.aborted === true) {
+            throw new WorkflowError('MockAdapter: request aborted', {
+                code: 'STEP_ABORTED',
+                category: 'ENGINE',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+        return this.resolve(operation);
+    }
+    async create(operation, _params, _config, signal) {
+        if (signal?.aborted === true) {
+            throw new WorkflowError('MockAdapter: request aborted', {
+                code: 'STEP_ABORTED',
+                category: 'ENGINE',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+        return this.resolve(operation);
+    }
+    async update(operation, _params, _config, signal) {
+        if (signal?.aborted === true) {
+            throw new WorkflowError('MockAdapter: request aborted', {
+                code: 'STEP_ABORTED',
+                category: 'ENGINE',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+        return this.resolve(operation);
+    }
+}
+//# sourceMappingURL=mock-adapter.js.map

package/dist/adapters/mock-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-adapter.js","sourceRoot":"","sources":["../../src/adapters/mock-adapter.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG3D;;;;GAIG;AACH,MAAM,OAAO,WAAW;IAEJ;IACC;IAFnB,YACkB,EAAU,EACT,SAA0C;QAD3C,OAAE,GAAF,EAAE,CAAQ;QACT,cAAS,GAAT,SAAS,CAAiC;IAC1D,CAAC;IAEI,OAAO,CAAC,SAAiB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,aAAa,CAAC,mCAAmC,SAAS,EAAE,EAAE;gBACtE,IAAI,EAAE,uBAAuB;gBAC7B,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,MAAM;gBACnB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,KAAK,CACT,SAAiB,EACjB,OAAgC,EAChC,OAAgC,EAChC,MAAoB;QAEpB,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,IAAI,aAAa,CAAC,8BAA8B,EAAE;gBACtD,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,gBAAgB;gBAC7B,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,MAAM,CACV,SAAiB,EACjB,OAAgC,EAChC,OAAgC,EAChC,MAAoB;QAEpB,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,IAAI,aAAa,CAAC,8BAA8B,EAAE;gBACtD,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,gBAAgB;gBAC7B,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,MAAM,CACV,SAAiB,EACjB,OAAgC,EAChC,OAAgC,EAChC,MAAoB;QAEpB,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,IAAI,aAAa,CAAC,8BAA8B,EAAE;gBACtD,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,gBAAgB;gBAC7B,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;CACF"}

package/dist/adapters/notion-adapter.d.ts

@@ -0,0 +1,54 @@
+import type { ServiceAdapter, ServiceResponse } from '../extensions/service-adapter.js';
+/**
+ * Configuration for NotionAdapter.
+ */
+export interface NotionAdapterConfig {
+    /**
+     * Notion integration token. Must be a non-empty string.
+     * Obtain from https://www.notion.so/my-integrations
+     */
+    api_key: string;
+    /**
+     * Override base URL for tests (replaces https://api.notion.com).
+     * Trailing slash is stripped.
+     */
+    base_url?: string;
+}
+/**
+ * NotionAdapter wraps the Notion REST API.
+ *
+ * Supported operations:
+ *   fetch('get_page', { page_id, filter_properties? })                      — GET  /v1/pages/{page_id}
+ *   fetch('list_block_children', { block_id, start_cursor?, page_size? })   — GET  /v1/blocks/{block_id}/children
+ *   fetch('query_data_source', { data_source_id, ...opts })                 — POST /v1/data_sources/{data_source_id}/query
+ *   fetch('search', { query?, filter?, sort?, start_cursor?, page_size? })  — POST /v1/search
+ *   create('create_page', { parent, properties?, children?, icon?, cover? }) — POST /v1/pages
+ *   create('append_block_children', { block_id, children, position? })      — PATCH /v1/blocks/{block_id}/children
+ *   update('update_page', { page_id, properties?, icon?, cover?, ... })     — PATCH /v1/pages/{page_id}
+ *   delete('delete_block', { block_id })                                    — DELETE /v1/blocks/{block_id}
+ */
+export declare class NotionAdapter implements ServiceAdapter {
+    readonly id: string;
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(id: string, config: NotionAdapterConfig);
+    private checkAborted;
+    private buildHeaders;
+    private buildUrl;
+    /**
+     * @param networkRetryable — set to false for non-idempotent write operations
+     *   (create_page, append_block_children) where retrying a failed request may
+     *   create duplicate resources.
+     */
+    private executeRequest;
+    private throwHttpError;
+    fetch(operation: string, params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    /**
+     * NOTE: retryable is false for network errors — retrying a failed create or append
+     * risks creating duplicate content if the server processed the request before the network dropped.
+     */
+    create(operation: string, params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    update(operation: string, params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    delete(operation: string, params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+}
+//# sourceMappingURL=notion-adapter.d.ts.map

package/dist/adapters/notion-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/notion-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAMxF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB;IASnD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,QAAQ;IAIhB;;;;OAIG;YACW,cAAc;YA0Cd,cAAc;IAyHtB,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAsP3B;;;OAGG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAiQrB,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAsErB,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;CAkD5B"}