@oomol-lab/open-connector 1.9.0 → 1.9.1

package/src/providers/sansan/executors.js

@@ -0,0 +1,59 @@
+import { optionalString, recordOrEmpty } from "../../core/cast.js";
+import { defineApiKeyProviderExecutors, defineProviderProxy, mapProviderActionHandlers, providerResponseError, requiredInputString, } from "../provider-runtime.js";
+import { sansanActions } from "./actions.js";
+import { sansanAdminHandlers } from "./admin.js";
+import { sansanBusinessHandlers } from "./business.js";
+import { sansanOrganizationHandlers } from "./organization.js";
+import { executeSansanRead } from "./read.js";
+import { readSansanError, requestSansanJson, sansanApiBaseUrl } from "./request.js";
+const mutations = { ...sansanAdminHandlers, ...sansanBusinessHandlers, ...sansanOrganizationHandlers };
+export const executors = defineApiKeyProviderExecutors("sansan", mapProviderActionHandlers("sansan", sansanActions, (action) => (input, context) => {
+    input = { ...input };
+    for (const field of [
+        "ownerUserId",
+        "businessCardId",
+        "personId",
+        "nextPageToken",
+        "departmentId",
+        "aclPatternId",
+        "aclPatternName",
+        "patternId",
+        "importId",
+    ]) {
+        if (input[field] !== undefined)
+            input[field] = requiredInputString(input[field], field);
+    }
+    for (const field of ["tagIds", "internalAttendeeUserIds"]) {
+        if (Array.isArray(input[field]))
+            input[field] = input[field].map((value) => requiredInputString(value, field));
+    }
+    if (Array.isArray(input.details))
+        input.details = input.details.map((value) => {
+            const detail = recordOrEmpty(value);
+            return {
+                ...detail,
+                objectDepartmentId: requiredInputString(detail.objectDepartmentId, "objectDepartmentId"),
+                accessibleFieldsSettingsName: requiredInputString(detail.accessibleFieldsSettingsName, "accessibleFieldsSettingsName"),
+            };
+        });
+    const handler = mutations[action.name];
+    return handler ? handler(input, context) : executeSansanRead(action.name, input, context);
+}));
+export const credentialValidators = {
+    async apiKey(input, { fetcher, signal }) {
+        const user = await requestSansanJson("/me", {}, { apiKey: input.apiKey, fetcher, signal, phase: "validate" });
+        const accountId = optionalString(user.id);
+        if (!accountId)
+            throw providerResponseError("Sansan user response is missing id");
+        return { profile: { accountId, displayName: optionalString(user.name) ?? accountId }, grantedScopes: [] };
+    },
+};
+export const proxy = defineProviderProxy({
+    service: "sansan",
+    baseUrl: sansanApiBaseUrl,
+    auth: { type: "api_key_header", name: "X-Sansan-Api-Key" },
+    readError: (response) => readSansanError(response),
+    customizeRequest({ headers }) {
+        headers.set("accept", "application/json");
+    },
+});

package/src/providers/sansan/file-schema.d.ts

@@ -0,0 +1,2 @@
+import type { JsonSchema } from "../../core/types.ts";
+export declare const sansanFileSchema: JsonSchema;

package/src/providers/sansan/file-schema.js

@@ -0,0 +1,8 @@
+import { s } from "../../core/json-schema.js";
+export const sansanFileSchema = s.actionOutput({
+    fileId: s.string("The stored transit file identifier."),
+    downloadUrl: s.string("The transit file download URL."),
+    name: s.string("The file name."),
+    mimeType: s.string("The file media type."),
+    sizeBytes: s.integer("The file size in bytes."),
+}, "A downloaded file in local transit storage.");

package/src/providers/sansan/files.d.ts

@@ -0,0 +1,11 @@
+import type { TransitFileUpload } from "../../core/types.ts";
+import type { ApiKeyProviderContext } from "../provider-runtime.ts";
+export declare function requireSansanTransit(context: ApiKeyProviderContext): void;
+export declare function downloadSansanSource(url: string, fieldName: string, context: ApiKeyProviderContext, jpeg?: boolean): Promise<Uint8Array>;
+interface SansanMultipart {
+    body: Uint8Array<ArrayBuffer>;
+    headers: Record<string, string>;
+}
+export declare function encodeSansanMultipart(form: FormData): Promise<SansanMultipart>;
+export declare function uploadSansanDownload(response: Response, name: string, mimeType: string, context: ApiKeyProviderContext): Promise<TransitFileUpload>;
+export {};

package/src/providers/sansan/files.js

@@ -0,0 +1,49 @@
+import { readBoundedResponseBytes, storeResponseInTransit } from "../../core/request.js";
+import { providerInputError, ProviderRequestError, providerResponseError, runProviderRequest, } from "../provider-runtime.js";
+export function requireSansanTransit(context) {
+    if (!context.transitFiles)
+        throw new ProviderRequestError(501, "Sansan downloads require transit file storage");
+}
+export async function downloadSansanSource(url, fieldName, context, jpeg = false) {
+    return runProviderRequest({ label: "Sansan source download", signal: context.signal }, async (signal) => {
+        const response = await context.fetcher(url, { signal });
+        if (!response.ok)
+            throw new ProviderRequestError(response.status, `Cannot download ${fieldName}`);
+        const bytes = await readBoundedResponseBytes(response, {
+            maxBytes: jpeg ? 5 * 1024 * 1024 : 20 * 1024 * 1024,
+            fieldName,
+            createError: providerInputError,
+            signal,
+        });
+        if (!bytes.length)
+            throw providerInputError(`${fieldName} is empty`);
+        if (jpeg && (bytes[0] !== 0xff || bytes[1] !== 0xd8 || bytes[2] !== 0xff))
+            throw providerInputError(`${fieldName} must contain a JPEG image`);
+        return bytes;
+    });
+}
+export async function encodeSansanMultipart(form) {
+    // Organization imports require a trailing CRLF and an explicit Content-Length.
+    const response = new Response(form);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const hasCrLf = bytes.at(-2) === 13 && bytes.at(-1) === 10;
+    const body = hasCrLf ? bytes : new Uint8Array(bytes.length + 2);
+    if (!hasCrLf) {
+        body.set(bytes);
+        body.set([13, 10], bytes.length);
+    }
+    return {
+        body,
+        headers: { "content-type": response.headers.get("content-type"), "content-length": String(body.byteLength) },
+    };
+}
+export function uploadSansanDownload(response, name, mimeType, context) {
+    requireSansanTransit(context);
+    return storeResponseInTransit(response, context.transitFiles, {
+        name,
+        mimeType: response.headers.get("content-type") || mimeType,
+        fieldName: "Sansan download",
+        createError: providerResponseError,
+        signal: context.signal,
+    });
+}

package/src/providers/sansan/organization-actions.d.ts

@@ -0,0 +1,2 @@
+import type { ActionDefinition } from "../../core/types.ts";
+export declare const sansanOrganizationActions: ActionDefinition[];

package/src/providers/sansan/organization-actions.js

@@ -0,0 +1,198 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+import { sansanFileSchema } from "./file-schema.js";
+const organizationImportInputSchema = {
+    ...s.object("Users and/or departments to check or import. System administrator only.", {
+        users: s.array("Structured user rows; Connector builds the official CSV, preserving all columns. Mutually exclusive with usersFileUrl.", s.object("A user import row using official Sansan CSV columns. Submission requires DepartmentId, UserId, UserName and Email; new users also require TempId and EffectiveDateFrom, while existing users require UserUuid. Blank optional cells preserve unchanged values when editing.", {
+            TempId: s.string("Temporary alphanumeric ID for a new user; blank when editing. Must be unique within the file.", { maxLength: 256 }),
+            UserUuid: s.string("Existing user UUID when editing; blank for a new user."),
+            DepartmentId: s.string("Department IDs separated by semicolons; use tempId:ID for a new department in the same import."),
+            UserId: s.string("Immutable user login ID, up to 20 characters; alphanumeric or .-_&.", { maxLength: 20 }),
+            UserName: s.string("User display name, up to 60 characters.", { maxLength: 60 }),
+            AlternativeName: s.string("User name reading.", { maxLength: 256 }),
+            Email: s.string("Unique primary user email within the company.", { maxLength: 60 }),
+            SubEmail: s.string("Secondary user email.", { maxLength: 60 }),
+            EffectiveDateFrom: s.string("Usage start date for new users, today or later in RFC3339 format; blank when unchanged during editing."),
+            SamlNameId: s.string("Unique SAML Name ID within the company."),
+            Culture: s.integer("Display language: 0 Japanese, 1 English, 2 Simplified Chinese. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 2 }),
+            MailFormat: s.integer("Email format: 0 HTML, 1 text. Omission serializes as a blank CSV cell.", {
+                minimum: 0,
+                maximum: 1,
+            }),
+            UserType: s.integer("Role: 0 regular, 1 system administrator, 2 departmental administrator. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 2 }),
+            CanUpdateData: s.integer("Permission to update all data: 1 granted, 0 denied. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 1 }),
+            DataDownloadPrivilege: s.integer("Download permission: 0 none, 1 own data, 2 all data, 3 assigned departments. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 3 }),
+            EmailDeliveryPrivilege: s.integer("Email delivery permission: 1 granted, 0 denied. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 1 }),
+            DealPrivilege: s.integer("Deal permission: 0 none, 1 regular, 2 administrator. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 2 }),
+            ApiIntegrationPrivilege: s.integer("API integration permission: 1 granted, 0 denied. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 1 }),
+            UsageStatisticsPrivilege: s.integer("Usage statistics permission: 1 granted, 0 denied. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 1 }),
+            OrganizationTreeDownloadPrivilege: s.integer("Organization tree download permission: 1 granted, 0 denied. Omission serializes as a blank CSV cell.", { minimum: 0, maximum: 1 }),
+            DeleteFlag: s.integer("Set to 1 to delete the user. Omission serializes as a blank CSV cell.", {
+                minimum: 0,
+                maximum: 1,
+            }),
+            SalesforceIntegrationPrivilege: s.string("Retired field, ignored by Sansan; the CSV column is retained even when omitted."),
+        }, { required: [] }), { minItems: 1 }),
+        departments: s.array("Structured department rows. Mutually exclusive with departmentsFileUrl.", s.object("A department import row using official Sansan CSV columns. Submission requires DepartmentName and either TempId for creation or DepartmentId for editing; the other identifier must be blank or omitted.", {
+            TempId: s.string("Temporary alphanumeric ID for a new department; blank when editing.", { maxLength: 256 }),
+            DepartmentId: s.string("Existing department ID when editing; blank for a new department."),
+            DepartmentName: s.string("Department name.", { maxLength: 30 }),
+            DepartmentNamePhonetic: s.string("Department name reading using lowercase Latin letters, digits, and spaces.", { maxLength: 256 }),
+            ParentDepartmentId: s.string("Parent department ID or tempId:ID for a parent created in the same import; blank for no parent."),
+            Order: s.integer("Department sort order."),
+            DeleteFlag: s.integer("Set to 1 to delete the department; it must have no users or child departments.", {
+                minimum: 0,
+                maximum: 1,
+            }),
+        }, { required: [] }), { minItems: 1 }),
+        usersFileUrl: s.string("Public URL of a UTF-8 user CSV with a header row; maximum 20 MiB per source file.", {
+            format: "uri",
+        }),
+        departmentsFileUrl: s.string("Public URL of a UTF-8 department CSV with a header row; maximum 20 MiB per source file.", { format: "uri" }),
+        delimiter: s.stringEnum("CSV delimiter; defaults to comma.", ["comma", "semicolon", "tab", "space"]),
+    }, { required: [] }),
+    anyOf: [
+        { required: ["users"] },
+        { required: ["departments"] },
+        { required: ["usersFileUrl"] },
+        { required: ["departmentsFileUrl"] },
+    ],
+    allOf: [
+        { not: { required: ["users", "usersFileUrl"] } },
+        { not: { required: ["departments", "departmentsFileUrl"] } },
+    ],
+};
+// Checking accepts incomplete rows for upstream diagnostics; submission enforces creation and update rules.
+const organizationSubmissionInputSchema = {
+    ...organizationImportInputSchema,
+    allOf: [
+        ...organizationImportInputSchema.allOf,
+        {
+            properties: {
+                users: {
+                    items: {
+                        required: ["DepartmentId", "UserId", "UserName", "Email"],
+                        properties: {
+                            DepartmentId: { minLength: 1 },
+                            UserId: { minLength: 1 },
+                            UserName: { minLength: 1 },
+                            Email: { minLength: 1 },
+                        },
+                        oneOf: [
+                            {
+                                required: ["TempId", "EffectiveDateFrom"],
+                                properties: {
+                                    TempId: { minLength: 1 },
+                                    UserUuid: { maxLength: 0 },
+                                    EffectiveDateFrom: { minLength: 1 },
+                                },
+                            },
+                            {
+                                required: ["UserUuid"],
+                                properties: {
+                                    UserUuid: { minLength: 1 },
+                                    TempId: { maxLength: 0 },
+                                },
+                            },
+                        ],
+                    },
+                },
+                departments: {
+                    items: {
+                        required: ["DepartmentName"],
+                        properties: { DepartmentName: { minLength: 1 } },
+                        oneOf: [
+                            {
+                                required: ["TempId"],
+                                properties: { TempId: { minLength: 1 }, DepartmentId: { maxLength: 0 } },
+                            },
+                            {
+                                required: ["DepartmentId"],
+                                properties: { DepartmentId: { minLength: 1 }, TempId: { maxLength: 0 } },
+                            },
+                        ],
+                    },
+                },
+            },
+        },
+    ],
+};
+export const sansanOrganizationActions = [
+    defineProviderAction("sansan", {
+        name: "export_organization_users",
+        description: "Export Sansan organization users as a CSV download. System administrator only.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("User export options.", {
+            delimiter: s.stringEnum("CSV delimiter; defaults to comma.", ["comma", "semicolon", "tab", "space"]),
+        }, { required: [] }),
+        outputSchema: sansanFileSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "export_organization_departments",
+        description: "Export Sansan organization departments as a CSV download. System administrator only.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Department export options.", {
+            delimiter: s.stringEnum("CSV delimiter; defaults to comma.", ["comma", "semicolon", "tab", "space"]),
+        }, { required: [] }),
+        outputSchema: sansanFileSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "check_organization_import",
+        description: "Validate user and department import data without applying changes. System administrator only; returns a downloadable CSV report if errors exist.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: organizationImportInputSchema,
+        outputSchema: s.object("Organization import validation result.", {
+            valid: s.boolean("Whether Sansan returned an empty validation response, indicating valid data."),
+            report: s.nullable(sansanFileSchema),
+        }, { required: ["valid", "report"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "submit_organization_import",
+        description: "Submit user and department additions, updates, or deletions. System administrator only. DeleteFlag can delete users or departments; preserve the import ID to retrieve results.",
+        operationType: "destructive",
+        requiredScopes: [],
+        inputSchema: organizationSubmissionInputSchema,
+        outputSchema: s.object("Submitted organization import.", {
+            importId: s.nonEmptyString("The submitted import job ID."),
+        }, { additionalProperties: true, required: ["importId"] }),
+        asyncLifecycle: {
+            startActionId: "sansan.submit_organization_import",
+            statusActionId: "sansan.get_organization_import_result",
+        },
+    }),
+    defineProviderAction("sansan", {
+        name: "get_organization_import_status",
+        description: "Get the current organization import status. System administrator only.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Organization import job identifier.", {
+            importId: s.nonEmptyString("The import ID returned when the job was submitted."),
+        }, { required: ["importId"] }),
+        outputSchema: s.object("Organization import status.", {
+            importStatus: s.integer("Upstream import status: 0 queued, 1 running, 2 completed, 9 error."),
+            status: s.stringEnum("Normalized import status.", ["queued", "running", "completed", "failed"]),
+        }, { additionalProperties: true, required: ["importStatus", "status"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "get_organization_import_result",
+        description: "Check an organization import and return its result CSV when completed or failed. System administrator only. The report includes created IDs and row-level errors.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Organization import job identifier.", {
+            importId: s.nonEmptyString("The import ID returned when the job was submitted."),
+        }, { required: ["importId"] }),
+        outputSchema: s.object("Organization import state and result report.", {
+            importId: s.nonEmptyString("The import ID."),
+            importStatus: s.integer("Upstream import status: 0 queued, 1 running, 2 completed, 9 error."),
+            status: s.stringEnum("Normalized import status.", ["queued", "running", "completed", "failed"]),
+            report: s.nullable(sansanFileSchema),
+        }, { additionalProperties: true, required: ["importId", "importStatus", "status", "report"] }),
+        asyncLifecycle: {
+            startActionId: "sansan.submit_organization_import",
+            statusActionId: "sansan.get_organization_import_result",
+        },
+    }),
+];

package/src/providers/sansan/organization-columns.d.ts

@@ -0,0 +1,2 @@
+export declare const sansanUserColumns: readonly string[];
+export declare const sansanDepartmentColumns: readonly string[];

package/src/providers/sansan/organization-columns.js

@@ -0,0 +1,33 @@
+export const sansanUserColumns = [
+    "TempId",
+    "UserUuid",
+    "DepartmentId",
+    "UserId",
+    "UserName",
+    "AlternativeName",
+    "Email",
+    "SubEmail",
+    "EffectiveDateFrom",
+    "Culture",
+    "MailFormat",
+    "SamlNameId",
+    "UserType",
+    "CanUpdateData",
+    "DataDownloadPrivilege",
+    "EmailDeliveryPrivilege",
+    "SalesforceIntegrationPrivilege",
+    "DealPrivilege",
+    "ApiIntegrationPrivilege",
+    "UsageStatisticsPrivilege",
+    "OrganizationTreeDownloadPrivilege",
+    "DeleteFlag",
+];
+export const sansanDepartmentColumns = [
+    "TempId",
+    "DepartmentId",
+    "DepartmentName",
+    "DepartmentNamePhonetic",
+    "ParentDepartmentId",
+    "Order",
+    "DeleteFlag",
+];

package/src/providers/sansan/organization.d.ts

@@ -0,0 +1,2 @@
+import type { SansanActionHandler } from "./request.ts";
+export declare const sansanOrganizationHandlers: Record<string, SansanActionHandler>;

package/src/providers/sansan/organization.js

@@ -0,0 +1,88 @@
+import { optionalNumber, optionalString } from "../../core/cast.js";
+import { providerResponseError, requiredResponseRecord } from "../provider-runtime.js";
+import { downloadSansanSource, encodeSansanMultipart, requireSansanTransit, uploadSansanDownload } from "./files.js";
+import { sansanDepartmentColumns, sansanUserColumns } from "./organization-columns.js";
+import { requestSansan, requestSansanJson, sansanPathId } from "./request.js";
+export const sansanOrganizationHandlers = {
+    async export_organization_users(input, context) {
+        return exportOrganization("users", input, context);
+    },
+    async export_organization_departments(input, context) {
+        return exportOrganization("departments", input, context);
+    },
+    async check_organization_import(input, context) {
+        const multipart = await buildOrganizationMultipart(input, context);
+        return requestSansan("/organization/check", { method: "POST", query: { delimiter: input.delimiter }, ...multipart }, context, async (response) => {
+            const csv = await response.text();
+            if (!csv.trim())
+                return { valid: true, report: null };
+            requireSansanTransit(context);
+            const report = await uploadSansanDownload(new Response(csv, { headers: { "content-type": "text/csv" } }), "sansan-import-validation.csv", "text/csv", context);
+            return { valid: false, report };
+        });
+    },
+    async submit_organization_import(input, context) {
+        const multipart = await buildOrganizationMultipart(input, context);
+        const result = await requestSansanJson("/organization/jobs", { method: "POST", query: { delimiter: input.delimiter }, ...multipart }, context);
+        if (!optionalString(result.importId))
+            throw providerResponseError("Sansan import response is missing importId");
+        return result;
+    },
+    async get_organization_import_status(input, context) {
+        return getImportStatus(input, context);
+    },
+    async get_organization_import_result(input, context) {
+        const result = await getImportStatus(input, context);
+        let report = null;
+        if (result.status === "completed" || result.status === "failed") {
+            requireSansanTransit(context);
+            const id = sansanPathId(input.importId, "importId");
+            report = await requestSansan(`/organization/jobs/${id}/result`, {}, context, (response) => uploadSansanDownload(response, "sansan-import-result.csv", "text/csv", context));
+        }
+        return { ...result, importId: input.importId, report };
+    },
+};
+async function exportOrganization(resource, input, context) {
+    requireSansanTransit(context);
+    return requestSansan(`/organization/${resource}`, { query: { delimiter: input.delimiter } }, context, (response) => uploadSansanDownload(response, `sansan-${resource}.csv`, "text/csv", context));
+}
+async function getImportStatus(input, context) {
+    const id = sansanPathId(input.importId, "importId");
+    const result = await requestSansanJson(`/organization/jobs/${id}`, {}, context);
+    const code = optionalNumber(result.importStatus);
+    const states = { 0: "queued", 1: "running", 2: "completed", 9: "failed" };
+    const status = code === undefined ? undefined : states[code];
+    if (!status)
+        throw providerResponseError("Sansan returned an unknown importStatus");
+    return { ...result, importStatus: code, status };
+}
+async function buildOrganizationMultipart(input, context) {
+    const form = new FormData();
+    const separators = { comma: ",", semicolon: ";", tab: "\t", space: " " };
+    const separator = separators[optionalString(input.delimiter) ?? "comma"];
+    for (const [field, part, columns] of [
+        ["users", "user", sansanUserColumns],
+        ["departments", "department", sansanDepartmentColumns],
+    ]) {
+        const urlField = `${field}FileUrl`;
+        if (input[urlField] !== undefined) {
+            const bytes = await downloadSansanSource(String(input[urlField]), urlField, context);
+            form.append(part, new Blob([bytes], { type: "text/csv" }), `${field}.csv`);
+        }
+        else if (Array.isArray(input[field])) {
+            const rows = input[field].map((row) => requiredResponseRecord(row, "Sansan import row"));
+            const csv = [
+                columns.join(separator),
+                ...rows.map((row) => columns.map((column) => csvCell(row[column], separator)).join(separator)),
+            ].join("\r\n") + "\r\n";
+            form.append(part, new Blob([csv], { type: "text/csv; charset=utf-8" }), `${field}.csv`);
+        }
+    }
+    return encodeSansanMultipart(form);
+}
+function csvCell(value, separator) {
+    const text = value === undefined || value === null ? "" : String(value);
+    return [separator, '"', "\r", "\n"].some((character) => text.includes(character))
+        ? `"${text.split('"').join('""')}"`
+        : text;
+}

package/src/providers/sansan/read.d.ts

@@ -0,0 +1,2 @@
+import type { SansanContext } from "./request.ts";
+export declare function executeSansanRead(name: string, input: Record<string, unknown>, context: SansanContext): Promise<Record<string, unknown>>;

package/src/providers/sansan/read.js

@@ -0,0 +1,25 @@
+import { providerInputError } from "../provider-runtime.js";
+import { normalizeSansanPage, requestSansanJson, sansanPageQuery, sansanPathId } from "./request.js";
+const actionRoutes = {
+    get_current_user: { path: "/me" },
+    list_business_cards: { path: "/bizCards", list: true },
+    search_business_cards: { path: "/bizCards/search", list: true },
+    get_business_card: { path: "/bizCards/{id}", idField: "businessCardId" },
+    get_person: { path: "/persons/{id}", idField: "personId" },
+    list_business_card_tags: { path: "/bizCards/{id}/tags", idField: "businessCardId", list: true },
+    list_tags: { path: "/tags", list: true },
+    list_contact_reports: { path: "/reports", list: true },
+};
+export async function executeSansanRead(name, input, context) {
+    const route = actionRoutes[name];
+    if (!route)
+        throw providerInputError(`Unknown Sansan read action: ${name}`);
+    const query = { ...input };
+    let path = route.path;
+    if (route.idField) {
+        path = path.replace("{id}", sansanPathId(query[route.idField], route.idField));
+        delete query[route.idField];
+    }
+    const result = await requestSansanJson(path, { query: sansanPageQuery(query) }, context);
+    return route.list ? normalizeSansanPage(result) : result;
+}

package/src/providers/sansan/request.d.ts

@@ -0,0 +1,22 @@
+import type { ApiKeyProviderContext } from "../provider-runtime.ts";
+import { ProviderRequestError } from "../provider-runtime.ts";
+export declare const sansanApiBaseUrl = "https://api.sansan.com/v6.0";
+export interface SansanContext extends ApiKeyProviderContext {
+    phase?: "validate" | "execute";
+}
+export type SansanActionHandler = (input: Record<string, unknown>, context: SansanContext) => Promise<unknown>;
+interface SansanRequest {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    query?: Record<string, unknown>;
+    json?: unknown;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+}
+export declare function requestSansan<T>(path: string, input: SansanRequest, context: SansanContext, consume: (response: Response) => Promise<T>): Promise<T>;
+export declare function requestSansanJson(path: string, input: SansanRequest, context: SansanContext): Promise<Record<string, unknown>>;
+export declare function readSansanJson(response: Response, allowEmpty?: boolean): Promise<unknown>;
+export declare function normalizeSansanPage(payload: Record<string, unknown>): Record<string, unknown>;
+export declare function sansanPathId(value: unknown, field: string): string;
+export declare function sansanPageQuery(query: Record<string, unknown>): Record<string, unknown>;
+export declare function readSansanError(response: Response, phase?: "validate" | "execute"): Promise<ProviderRequestError>;
+export {};

package/src/providers/sansan/request.js

@@ -0,0 +1,94 @@
+import { looseArray, optionalRecord, optionalString } from "../../core/cast.js";
+import { ProviderRequestError, providerInputError, providerResponseError, providerUserAgent, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+export const sansanApiBaseUrl = "https://api.sansan.com/v6.0";
+export async function requestSansan(path, input, context, consume) {
+    return runProviderRequest({ label: "Sansan", signal: context.signal }, async (signal) => {
+        const url = new URL(`${sansanApiBaseUrl}${path}`);
+        for (const [key, value] of Object.entries(input.query ?? {})) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                const parameter = key === "tagIds" ? "tagId[]" : path === "/reports" ? `${key}[]` : key;
+                for (const item of value)
+                    url.searchParams.append(parameter, String(item));
+            }
+            else {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = new Headers(input.headers);
+        headers.set("X-Sansan-Api-Key", context.apiKey);
+        headers.set("accept", "application/json, text/csv, image/jpeg");
+        headers.set("user-agent", providerUserAgent);
+        if (input.json !== undefined)
+            headers.set("content-type", "application/json");
+        const response = await context.fetcher(url, {
+            method: input.method ?? "GET",
+            headers,
+            body: input.json === undefined ? input.body : JSON.stringify(input.json),
+            signal,
+        });
+        if (!response.ok)
+            throw await readSansanError(response, context.phase ?? "execute");
+        return consume(response);
+    });
+}
+export function requestSansanJson(path, input, context) {
+    return requestSansan(path, input, context, async (response) => requiredResponseRecord(await readSansanJson(response), "Sansan response"));
+}
+export async function readSansanJson(response, allowEmpty = false) {
+    const text = await response.text();
+    if (allowEmpty && !text.trim())
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw providerResponseError("Sansan returned invalid JSON");
+    }
+}
+export function normalizeSansanPage(payload) {
+    if (!Array.isArray(payload.data) || typeof payload.hasMore !== "boolean") {
+        throw providerResponseError("Sansan list response is missing data or hasMore");
+    }
+    const nextPageToken = optionalString(payload.nextPageToken) || null;
+    if (payload.hasMore && !nextPageToken) {
+        throw providerResponseError("Sansan list response is missing nextPageToken");
+    }
+    return { ...payload, data: payload.data, hasMore: payload.hasMore, nextPageToken };
+}
+export function sansanPathId(value, field) {
+    const id = optionalString(value)?.trim();
+    if (!id || id === "." || id === "..") {
+        throw providerInputError(`${field} must be a non-empty resource ID, not a dot path segment`);
+    }
+    return encodeURIComponent(id);
+}
+export function sansanPageQuery(query) {
+    const token = optionalString(query.nextPageToken);
+    return token ? { nextPageToken: token } : query;
+}
+export async function readSansanError(response, phase = "execute") {
+    const text = await response.text();
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        value = { message: text };
+    }
+    const payload = optionalRecord(value);
+    const codes = looseArray(payload?.error).flatMap((detail) => {
+        const item = optionalRecord(detail);
+        const code = optionalString(item?.Code) ?? optionalString(item?.code);
+        return code ? [code] : [];
+    });
+    const detail = optionalString(payload?.message) || `Sansan request failed with status ${response.status}`;
+    const message = codes.length ? `${detail} (${codes.join(", ")})` : detail;
+    if (codes.includes("invalid_api_key")) {
+        return new ProviderRequestError(phase === "validate" ? 400 : 409, message, undefined, phase === "validate" ? "invalid_input" : "authorization_failed");
+    }
+    if (response.status === 429)
+        return new ProviderRequestError(429, message, undefined, "rate_limited");
+    return new ProviderRequestError(response.status, message, undefined, "provider_error");
+}

package/src/providers/sansan/schemas.d.ts

@@ -0,0 +1,7 @@
+import type { JsonSchema } from "../../core/types.ts";
+export declare const businessCardSchema: JsonSchema;
+export declare const userSchema: JsonSchema;
+export declare const reportSchema: JsonSchema;
+export declare const businessCardPageSchema: JsonSchema;
+export declare const tagPageSchema: JsonSchema;
+export declare const reportPageSchema: JsonSchema;