@oomol-lab/open-connector 1.9.0 → 1.9.2

package/src/providers/salesforce/runtime-leads.js

@@ -0,0 +1,117 @@
+import XMLBuilder from "fast-xml-builder";
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+import { optionalString, recordOrEmpty } from "../../core/cast.js";
+import { ProviderRequestError, providerInputError, providerResponseError, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+const builder = new XMLBuilder({ ignoreAttributes: false });
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    removeNSPrefix: true,
+    parseTagValue: false,
+    processEntities: true,
+});
+const conversionFields = [
+    "accountId",
+    "contactId",
+    "convertedStatus",
+    "doNotCreateOpportunity",
+    "leadId",
+    "opportunityId",
+    "opportunityName",
+    "overwriteLeadSource",
+    "ownerId",
+    "relatedPersonAccountId",
+    "relatedPersonAccountRecord",
+    "sendNotificationEmail",
+];
+export const salesforceLeadHandlers = {
+    async convert_leads(d, c) {
+        const conversions = d.conversions;
+        const leadConverts = conversions.map((entry) => {
+            if ((entry.opportunityId !== undefined && entry.opportunityName !== undefined) ||
+                (entry.doNotCreateOpportunity === true &&
+                    (entry.opportunityId !== undefined || entry.opportunityName !== undefined)))
+                throw providerInputError("Opportunity ID, name and doNotCreateOpportunity conflict");
+            if ((entry.contactId !== undefined || entry.overwriteLeadSource === true) && entry.accountId === undefined)
+                throw providerInputError("An existing contact requires accountId");
+            if (entry.overwriteLeadSource === true && entry.contactId === undefined)
+                throw providerInputError("overwriteLeadSource requires contactId");
+            if (entry.relatedPersonAccountId !== undefined && entry.relatedPersonAccountRecord !== undefined)
+                throw providerInputError("Choose an existing or new related Person Account");
+            const result = {};
+            for (const key of conversionFields) {
+                if (entry[key] === undefined &&
+                    !["doNotCreateOpportunity", "overwriteLeadSource", "sendNotificationEmail"].includes(key))
+                    continue;
+                if (key === "relatedPersonAccountRecord") {
+                    const fields = recordOrEmpty(recordOrEmpty(entry[key]).fields);
+                    const entity = {
+                        "obj:type": "Account",
+                        "obj:fieldsToNull": Object.entries(fields)
+                            .filter(([, value]) => value === null)
+                            .map(([name]) => name),
+                    };
+                    for (const [name, value] of Object.entries(fields)) {
+                        if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name) || name === "type" || name === "fieldsToNull")
+                            throw providerInputError("Invalid Person Account field API name");
+                        if (value !== null)
+                            entity[`obj:${name}`] = value;
+                    }
+                    result[key] = entity;
+                }
+                else
+                    result[key] = entry[key] ?? false;
+            }
+            return result;
+        });
+        const xml = builder.build({
+            "env:Envelope": {
+                "@_xmlns:env": "http://schemas.xmlsoap.org/soap/envelope/",
+                "@_xmlns": "urn:partner.soap.sforce.com",
+                "@_xmlns:obj": "urn:sobject.partner.soap.sforce.com",
+                "env:Header": { SessionHeader: { sessionId: c.accessToken } },
+                "env:Body": { convertLead: { leadConverts } },
+            },
+        });
+        return runProviderRequest({ label: "Salesforce", signal: c.signal }, async (signal) => {
+            const response = await c.fetcher(new URL(`/services/Soap/u/${c.version}`, c.origin), {
+                method: "POST",
+                headers: {
+                    "content-type": "text/xml; charset=UTF-8",
+                    accept: "text/xml",
+                    SOAPAction: "convertLead",
+                },
+                body: xml,
+                signal,
+                redirect: "manual",
+            });
+            const text = await response.text();
+            if (text.includes("<!DOCTYPE") || text.includes("<!ENTITY") || XMLValidator.validate(text) !== true)
+                throw new ProviderRequestError(response.ok ? 502 : response.status, "Salesforce returned invalid SOAP XML", undefined, "provider_error");
+            const body = recordOrEmpty(recordOrEmpty(parser.parse(text)).Envelope).Body;
+            const envelope = requiredResponseRecord(body, "Salesforce SOAP body");
+            const fault = recordOrEmpty(envelope.Fault);
+            if (envelope.Fault || !response.ok) {
+                const message = [optionalString(fault.faultcode), optionalString(fault.faultstring)].filter(Boolean).join(": ");
+                throw new ProviderRequestError(response.ok ? 502 : response.status, `Salesforce: ${message || `HTTP ${response.status}`}`.split(c.accessToken).join("[REDACTED]"), undefined, "provider_error");
+            }
+            const raw = recordOrEmpty(envelope.convertLeadResponse).result;
+            if (raw === undefined)
+                throw providerResponseError("Salesforce SOAP response is missing conversion results");
+            const results = (Array.isArray(raw) ? raw : [raw]).map((value) => {
+                const result = requiredResponseRecord(value, "Salesforce conversion result");
+                if (!["true", "false", "1", "0"].includes(String(result.success)))
+                    throw providerResponseError("Salesforce conversion result is missing success");
+                return {
+                    ...result,
+                    success: result.success === "true" || result.success === "1",
+                    leadId: optionalString(result.leadId) ?? null,
+                    accountId: optionalString(result.accountId) ?? null,
+                    contactId: optionalString(result.contactId) ?? null,
+                    opportunityId: optionalString(result.opportunityId) ?? null,
+                    errors: result.errors === undefined ? [] : Array.isArray(result.errors) ? result.errors : [result.errors],
+                };
+            });
+            return { results };
+        });
+    },
+};

package/src/providers/salesforce/runtime-platform.d.ts

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

package/src/providers/salesforce/runtime-platform.js

@@ -0,0 +1,67 @@
+import { providerInputError } from "../provider-runtime.js";
+import { queryPath, segment } from "./context.js";
+export const salesforcePlatformHandlers = {
+    async get_record_create_defaults(d, c) {
+        return c.object(queryPath(`${c.base}/ui-api/record-defaults/create/${segment(d.objectName)}`, {
+            recordTypeId: d.recordTypeId,
+            formFactor: d.formFactor,
+            optionalFields: d.optionalFields,
+        }));
+    },
+    async get_record_layout(d, c) {
+        return {
+            layout: await c.object(queryPath(`${c.base}/ui-api/layout/${segment(d.objectName)}`, {
+                recordTypeId: d.recordTypeId,
+                formFactor: d.formFactor,
+                layoutType: d.layoutType,
+                mode: d.mode,
+            })),
+        };
+    },
+    async get_lookup_suggestions(d, c) {
+        const q = String(d.q ?? "");
+        if ((d.searchType === "Search" && q.length < 2) ||
+            (d.searchType === "TypeAhead" && (q.length < 3 || q.includes("?"))))
+            throw providerInputError("Lookup search text does not meet the selected searchType requirements");
+        if (Number(c.version) < 60 || (d.orderBy !== undefined && Number(c.version) < 63))
+            throw providerInputError("Lookup POST requires API 60.0; orderBy requires API 63.0");
+        return {
+            result: await c.object(queryPath(`${c.base}/ui-api/lookups/${segment(d.objectName)}/${segment(d.fieldName)}`, {
+                searchType: d.searchType,
+                q: d.q,
+                page: d.page,
+                pageSize: d.pageSize,
+                targetApiName: d.targetApiName,
+            }), "POST", { sourceRecord: { fields: d.sourceFields }, orderBy: d.orderBy }),
+        };
+    },
+    async create_report(d, c) {
+        return c.object(`${c.base}/analytics/reports`, "POST", { reportMetadata: d.reportMetadata });
+    },
+    async clone_report(d, c) {
+        return c.object(queryPath(`${c.base}/analytics/reports`, { cloneId: d.reportId }), "POST", {
+            reportMetadata: d.reportMetadata ?? {},
+        });
+    },
+    async save_report(d, c) {
+        return c.object(`${c.base}/analytics/reports/${segment(d.reportId)}`, "PATCH", {
+            reportMetadata: d.reportMetadata,
+        });
+    },
+    async tooling_query(d, c) {
+        return c.object(queryPath(`${c.base}/tooling/query`, { q: d.soql }));
+    },
+    async tooling_query_more(d, c) {
+        return c.object(String(d.nextRecordsUrl));
+    },
+    async get_tooling_record(d, c) {
+        return {
+            record: await c.object(queryPath(`${c.base}/tooling/sobjects/${segment(d.objectName)}/${segment(d.recordId)}`, {
+                fields: d.fields,
+            })),
+        };
+    },
+    async get_apex_log(d, c) {
+        return c.response(`${c.base}/tooling/sobjects/ApexLog/${segment(d.logId)}/Body`, { headers: { accept: "text/plain" } }, async (response) => ({ body: await response.text() }));
+    },
+};

package/src/providers/salesforce/transport.d.ts

@@ -0,0 +1,9 @@
+import { ProviderRequestError } from "../provider-runtime.ts";
+export declare const salesforceFileRequestTimeoutMs = 300000;
+export declare function salesforceOrigin(value: string, fieldName: string): string;
+export declare function withSalesforceResponse<T>(url: URL, init: RequestInit, fetcher: typeof fetch, consume: (response: Response, signal: AbortSignal) => Promise<T>, timeoutMs?: number, parentSignal?: AbortSignal): Promise<T>;
+export declare function readSalesforceError(response: Response): Promise<ProviderRequestError>;
+export declare function salesforceRequest(url: URL, init: RequestInit, fetcher: typeof fetch, signal?: AbortSignal): Promise<{
+    status: number;
+    body: unknown;
+}>;

package/src/providers/salesforce/transport.js

@@ -0,0 +1,65 @@
+import { optionalRecord, optionalString } from "../../core/cast.js";
+import { assertPublicHttpUrl } from "../../core/request.js";
+import { isAbortLikeError, providerInputError, providerResponseError, ProviderRequestError, providerUserAgent, runProviderRequest, } from "../provider-runtime.js";
+// File transfers have a deliberate five-minute budget; JSON uses the shared default.
+export const salesforceFileRequestTimeoutMs = 300_000;
+export function salesforceOrigin(value, fieldName) {
+    const url = assertPublicHttpUrl(value, { fieldName, createError: providerInputError });
+    if (url.protocol !== "https:" ||
+        !url.hostname.endsWith(".salesforce.com") ||
+        url.port ||
+        url.username ||
+        url.password ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash) {
+        throw providerInputError(`${fieldName} must be a Salesforce HTTPS origin`);
+    }
+    return url.origin;
+}
+export async function withSalesforceResponse(url, init, fetcher, consume, timeoutMs, parentSignal) {
+    return runProviderRequest({ label: "Salesforce", timeoutMs, signal: parentSignal }, async (signal) => {
+        const headers = new Headers(init.headers);
+        if (!headers.has("accept"))
+            headers.set("accept", "application/json");
+        headers.set("user-agent", providerUserAgent);
+        const request = {
+            ...init,
+            headers,
+            signal,
+            redirect: "manual",
+            duplex: init.body instanceof ReadableStream ? "half" : undefined,
+        };
+        const response = await fetcher(url, request);
+        if (!response.ok)
+            throw await readSalesforceError(response);
+        return consume(response, signal);
+    });
+}
+export async function readSalesforceError(response) {
+    const payload = await response.json().catch((error) => {
+        if (isAbortLikeError(error))
+            throw error;
+        return undefined;
+    });
+    const error = optionalRecord(Array.isArray(payload) ? payload[0] : payload);
+    const code = optionalString(error?.errorCode) ?? optionalString(error?.error);
+    const message = optionalString(error?.message) ?? optionalString(error?.error_description);
+    // INVALID_SESSION_ID proves only the access token expired, not the refresh token.
+    return new ProviderRequestError(response.status, ["Salesforce", code, message ?? `HTTP ${response.status}`].filter(Boolean).join(": "), { errorCode: code, errorDescription: message }, "provider_error");
+}
+export function salesforceRequest(url, init, fetcher, signal) {
+    return withSalesforceResponse(url, init, fetcher, async (response) => {
+        const text = response.status === 204 ? "" : await response.text();
+        let body;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                throw providerResponseError("Salesforce returned invalid JSON");
+            }
+        }
+        return { status: response.status, body };
+    }, undefined, signal);
+}

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

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

package/src/providers/sansan/actions.js

@@ -0,0 +1,165 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+import { sansanAdminActions } from "./admin-actions.js";
+import { sansanBusinessActions } from "./business-actions.js";
+import { sansanOrganizationActions } from "./organization-actions.js";
+import { businessCardSchema, reportPageSchema, businessCardPageSchema, tagPageSchema, userSchema } from "./schemas.js";
+export const sansanActions = [
+    ...sansanBusinessActions,
+    ...sansanOrganizationActions,
+    ...sansanAdminActions,
+    defineProviderAction("sansan", {
+        name: "get_current_user",
+        operationType: "read",
+        description: "Get the Sansan user and permissions associated with the connected API key.",
+        requiredScopes: [],
+        inputSchema: s.object("No input is required.", {}, { required: [] }),
+        outputSchema: userSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "list_business_cards",
+        operationType: "read",
+        description: "List business cards updated within a time interval, with optional historical cards and tags. Use nextPageToken to continue.",
+        requiredScopes: [],
+        inputSchema: {
+            ...s.object("Business card update query.", {
+                nextPageToken: s.nonEmptyString("Continue a previous query using its nextPageToken; original query parameters are inherited."),
+                limit: s.integer("Maximum records per page, from 1 to 300; defaults to 100.", {
+                    minimum: 1,
+                    maximum: 300,
+                }),
+                range: s.stringEnum("Record ownership scope: me or all accessible records; defaults to me.", ["me", "all"]),
+                includeTags: s.boolean("Include attached tags and treat tag changes as business card updates."),
+                includePastBizCards: s.boolean("Include older business cards for merged persons; defaults to false."),
+                entryStatus: s.array("Digitization statuses to include; defaults to completed.", s.stringEnum("A business card digitization status.", ["processing", "completed", "unreadable"])),
+                orderBy: s.stringEnum("Sort field; defaults to updatedAt for listing and registeredAt for searching.", [
+                    "registeredAt",
+                    "completedAt",
+                    "updatedAt",
+                ]),
+                orderDirection: s.stringEnum("Sort direction; defaults to asc for listing and desc for searching.", [
+                    "asc",
+                    "desc",
+                ]),
+                updatedFrom: s.string("Start of the update interval as an ISO 8601 timestamp with timezone. Required on the first page.", { format: "date-time" }),
+                updatedTo: s.string("End of the update interval as an ISO 8601 timestamp with timezone. Required on the first page.", { format: "date-time" }),
+            }, { required: [] }),
+            anyOf: [{ required: ["nextPageToken"] }, { required: ["updatedFrom", "updatedTo"] }],
+        },
+        outputSchema: businessCardPageSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "search_business_cards",
+        operationType: "read",
+        description: "Search accessible Sansan business cards by company, name, email, telephone, mobile, and tags.",
+        requiredScopes: [],
+        inputSchema: s.object("Business card search filters.", {
+            nextPageToken: s.nonEmptyString("Continue a previous query using its nextPageToken; original query parameters are inherited."),
+            limit: s.integer("Maximum records per page, from 1 to 300; defaults to 100.", {
+                minimum: 1,
+                maximum: 300,
+            }),
+            range: s.stringEnum("Record ownership scope: me or all accessible records; defaults to me.", ["me", "all"]),
+            includeTags: s.boolean("Include attached tags and treat tag changes as business card updates."),
+            includePastBizCards: s.boolean("Include older business cards for merged persons; defaults to false."),
+            entryStatus: s.array("Digitization statuses to include; defaults to completed.", s.stringEnum("A business card digitization status.", ["processing", "completed", "unreadable"])),
+            orderBy: s.stringEnum("Sort field; defaults to updatedAt for listing and registeredAt for searching.", [
+                "registeredAt",
+                "completedAt",
+                "updatedAt",
+            ]),
+            orderDirection: s.stringEnum("Sort direction; defaults to asc for listing and desc for searching.", [
+                "asc",
+                "desc",
+            ]),
+            companyName: s.string("Company name substring."),
+            name: s.string("Name prefix."),
+            email: s.string("Exact email address."),
+            tel: s.string("Telephone number substring."),
+            mobile: s.string("Mobile number substring."),
+            tagIds: s.array("Filter by one or more Sansan tag IDs.", s.nonEmptyString("A tag ID.")),
+        }, { required: [] }),
+        outputSchema: businessCardPageSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "get_business_card",
+        operationType: "read",
+        description: "Get a business card by ID. Sansan may return the latest merged card with a different ID.",
+        requiredScopes: [],
+        inputSchema: s.object("Business card lookup.", {
+            businessCardId: s.nonEmptyString("The Sansan business card ID."),
+            includeTags: s.boolean("Include attached tags and treat tag changes as business card updates."),
+        }, { required: ["businessCardId"] }),
+        outputSchema: businessCardSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "get_person",
+        operationType: "read",
+        description: "Get the latest business card for a Sansan person, optionally including tags.",
+        requiredScopes: [],
+        inputSchema: s.object("Person lookup.", {
+            personId: s.nonEmptyString("The Sansan person ID."),
+            includeTags: s.boolean("Include attached tags and treat tag changes as business card updates."),
+        }, { required: ["personId"] }),
+        outputSchema: businessCardSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "list_business_card_tags",
+        operationType: "read",
+        description: "List tags attached to a Sansan business card.",
+        requiredScopes: [],
+        inputSchema: s.object("Business card tag query.", {
+            businessCardId: s.nonEmptyString("The Sansan business card ID."),
+            nextPageToken: s.nonEmptyString("Continue a previous query using its nextPageToken; original query parameters are inherited."),
+            limit: s.integer("Maximum records per page, from 1 to 300; defaults to 100.", {
+                minimum: 1,
+                maximum: 300,
+            }),
+        }, { required: ["businessCardId"] }),
+        outputSchema: tagPageSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "list_tags",
+        operationType: "read",
+        description: "List Sansan tags by ownership, visibility, owner user, and tag name.",
+        requiredScopes: [],
+        inputSchema: s.object("Tag query filters.", {
+            nextPageToken: s.nonEmptyString("Continue a previous query using its nextPageToken; original query parameters are inherited."),
+            limit: s.integer("Maximum records per page, from 1 to 300; defaults to 100.", {
+                minimum: 1,
+                maximum: 300,
+            }),
+            range: s.stringEnum("Record ownership scope: me or all accessible records; defaults to me.", ["me", "all"]),
+            type: s.array("Tag visibility types to include.", s.stringEnum("A tag visibility type.", ["private", "public", "shared"])),
+            ownerUserId: s.string("Tag owner user ID, effective only when range is all.", {
+                maxLength: 20,
+            }),
+            tagName: s.string("Tag name substring.", { maxLength: 50 }),
+        }, { required: [] }),
+        outputSchema: tagPageSchema,
+    }),
+    defineProviderAction("sansan", {
+        name: "list_contact_reports",
+        operationType: "read",
+        description: "List Sansan contact reports updated within a time interval, including meetings, calls, emails, and business card exchanges.",
+        requiredScopes: [],
+        inputSchema: {
+            ...s.object("Contact report query filters.", {
+                nextPageToken: s.nonEmptyString("Continue a previous query using its nextPageToken; original query parameters are inherited."),
+                limit: s.integer("Maximum records per page, from 1 to 300; defaults to 100.", {
+                    minimum: 1,
+                    maximum: 300,
+                }),
+                updatedFrom: s.string("Start of the update interval as an ISO 8601 timestamp with timezone. Required on the first page.", { format: "date-time" }),
+                updatedTo: s.string("End of the update interval as an ISO 8601 timestamp with timezone. Required on the first page.", { format: "date-time" }),
+                range: s.stringEnum("Record ownership scope: me or all accessible records; defaults to me.", ["me", "all"]),
+                category: s.array("Exact category names to include.", s.string("A report category.")),
+                type: s.array("Contact report types to include.", s.stringEnum("A contact report type.", ["Meeting", "Call", "Email", "BizCardExchange", "OnlineMeeting"])),
+                orderBy: s.stringEnum("Sort field; defaults to updatedAt.", ["registeredAt", "updatedAt"]),
+                orderDirection: s.stringEnum("Sort direction; defaults to desc.", ["asc", "desc"]),
+            }, { required: [] }),
+            anyOf: [{ required: ["nextPageToken"] }, { required: ["updatedFrom", "updatedTo"] }],
+        },
+        outputSchema: reportPageSchema,
+    }),
+];

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

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

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

@@ -0,0 +1,181 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+export const sansanAdminActions = [
+    defineProviderAction("sansan", {
+        name: "list_departments",
+        description: "List administrative department IDs, names, and parents. System administrator only.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Department pagination.", {
+            nextPageToken: s.nonEmptyString("Continue with the next page token; original filters are inherited."),
+        }, { required: [] }),
+        outputSchema: s.object("A page of administration records.", {
+            data: s.array("Records in this page.", s.object("An administrative department.", {
+                id: s.nonEmptyString("The department ID."),
+                name: s.string("Department name."),
+                parentId: s.nullable(s.string("Parent department ID.")),
+            }, { additionalProperties: true, required: [] })),
+            hasMore: s.boolean("Whether another page is available."),
+            nextPageToken: s.nullable(s.string("The next page token, or null.")),
+        }, { additionalProperties: true, required: ["data", "hasMore", "nextPageToken"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "get_department_access_control",
+        description: "Get the access control pattern assigned to a department. System administrator only.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Department selection.", {
+            departmentId: s.nonEmptyString("The department ID."),
+        }, { required: ["departmentId"] }),
+        outputSchema: s.object("Department access control assignment.", {
+            departmentId: s.nonEmptyString("The department ID."),
+            accessControlPattern: s.object("A Sansan access control pattern, including upstream-defined fields.", {
+                aclPatternId: s.nonEmptyString("The access control pattern ID."),
+                aclPatternName: s.nonEmptyString("Access control pattern name."),
+                description: s.string("Access control pattern description."),
+                details: s.array("Department access rules.", s.object("Access rule for a target department; additional provider-defined fields are accepted.", {
+                    objectDepartmentId: s.nonEmptyString("The department whose data this rule covers."),
+                    accessibleFieldsSettingsName: s.nonEmptyString("The upstream accessible-fields setting name, such as ALL. Use values configured in Sansan; no complete enum is published."),
+                }, { additionalProperties: true, required: ["objectDepartmentId", "accessibleFieldsSettingsName"] })),
+                isInUse: s.boolean("Whether this pattern is in use."),
+            }, { additionalProperties: true, required: [] }),
+        }, { additionalProperties: true, required: [] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "set_department_access_control",
+        description: "Assign an access control pattern to a department. System administrator only.",
+        operationType: "write",
+        requiredScopes: [],
+        inputSchema: s.object("Department and pattern assignment.", {
+            departmentId: s.nonEmptyString("The department ID."),
+            aclPatternId: s.nonEmptyString("The access control pattern ID."),
+        }, { required: ["departmentId", "aclPatternId"] }),
+        outputSchema: s.object("Successful administration change.", {
+            success: s.boolean("Whether the request succeeded."),
+            data: s.nullable(s.unknownObject("Any JSON payload returned by Sansan.")),
+        }, { required: ["success", "data"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "list_access_control_patterns",
+        description: "List access control patterns, optionally filtering by a name substring. System administrator only.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("Access control pattern search.", {
+            nextPageToken: s.nonEmptyString("Continue with the next page token; original filters are inherited."),
+            name: s.string("Pattern name substring."),
+        }, { required: [] }),
+        outputSchema: s.object("A page of administration records.", {
+            data: s.array("Records in this page.", s.object("A Sansan access control pattern, including upstream-defined fields.", {
+                aclPatternId: s.nonEmptyString("The access control pattern ID."),
+                aclPatternName: s.nonEmptyString("Access control pattern name."),
+                description: s.string("Access control pattern description."),
+                details: s.array("Department access rules.", s.object("Access rule for a target department; additional provider-defined fields are accepted.", {
+                    objectDepartmentId: s.nonEmptyString("The department whose data this rule covers."),
+                    accessibleFieldsSettingsName: s.nonEmptyString("The upstream accessible-fields setting name, such as ALL. Use values configured in Sansan; no complete enum is published."),
+                }, { additionalProperties: true, required: ["objectDepartmentId", "accessibleFieldsSettingsName"] })),
+                isInUse: s.boolean("Whether this pattern is in use."),
+            }, { additionalProperties: true, required: [] })),
+            hasMore: s.boolean("Whether another page is available."),
+            nextPageToken: s.nullable(s.string("The next page token, or null.")),
+        }, { additionalProperties: true, required: ["data", "hasMore", "nextPageToken"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "create_access_control_pattern",
+        description: "Create an access control pattern with department access rules. System administrator only.",
+        operationType: "write",
+        requiredScopes: [],
+        inputSchema: s.object("New access control pattern.", {
+            aclPatternName: s.nonEmptyString("Access control pattern name."),
+            description: s.string("Access control pattern description."),
+            details: s.array("Department access rules.", s.object("Access rule for a target department; additional provider-defined fields are accepted.", {
+                objectDepartmentId: s.nonEmptyString("The department whose data this rule covers."),
+                accessibleFieldsSettingsName: s.nonEmptyString("The upstream accessible-fields setting name, such as ALL. Use values configured in Sansan; no complete enum is published."),
+            }, { additionalProperties: true, required: ["objectDepartmentId", "accessibleFieldsSettingsName"] })),
+        }, { required: ["aclPatternName", "details"] }),
+        outputSchema: s.object("Created access control pattern.", {
+            id: s.nonEmptyString("The access control pattern ID."),
+        }, { additionalProperties: true, required: ["id"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "update_access_control_pattern",
+        description: "Update an access control pattern and its department rules. System administrator only.",
+        operationType: "write",
+        requiredScopes: [],
+        inputSchema: s.object("Access control pattern changes.", {
+            patternId: s.nonEmptyString("The access control pattern ID."),
+            aclPatternName: s.nonEmptyString("Access control pattern name."),
+            description: s.string("Access control pattern description."),
+            details: s.array("Department access rules.", s.object("Access rule for a target department; additional provider-defined fields are accepted.", {
+                objectDepartmentId: s.nonEmptyString("The department whose data this rule covers."),
+                accessibleFieldsSettingsName: s.nonEmptyString("The upstream accessible-fields setting name, such as ALL. Use values configured in Sansan; no complete enum is published."),
+            }, { additionalProperties: true, required: ["objectDepartmentId", "accessibleFieldsSettingsName"] })),
+        }, { required: ["patternId"] }),
+        outputSchema: s.object("Successful administration change.", {
+            success: s.boolean("Whether the request succeeded."),
+            data: s.nullable(s.unknownObject("Any JSON payload returned by Sansan.")),
+        }, { required: ["success", "data"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "delete_access_control_pattern",
+        description: "Delete an access control pattern. System administrator only; Sansan may reject a pattern still in use.",
+        operationType: "destructive",
+        requiredScopes: [],
+        inputSchema: s.object("Access control pattern to delete.", {
+            patternId: s.nonEmptyString("The access control pattern ID."),
+        }, { required: ["patternId"] }),
+        outputSchema: s.object("Successful administration change.", {
+            success: s.boolean("Whether the request succeeded."),
+            data: s.nullable(s.unknownObject("Any JSON payload returned by Sansan.")),
+        }, { required: ["success", "data"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "get_default_email_client",
+        description: "Get the default email client settings for new users. System administrator only.",
+        operationType: "read",
+        requiredScopes: [],
+        inputSchema: s.object("No input is required.", {}, { required: [] }),
+        outputSchema: s.object("Organization default email client; null when not configured.", {
+            settings: s.nullable(s.object("Email client configuration.", {
+                emailClient: s.stringEnum("Default email client for newly added users.", [
+                    "clientSoftware",
+                    "gmail",
+                    "office365",
+                ]),
+                encoding: s.stringEnum("Required only for clientSoftware.", ["sjis", "utf8", "iso2022jp"]),
+            }, { additionalProperties: true, required: [] })),
+        }, { required: ["settings"] }),
+    }),
+    defineProviderAction("sansan", {
+        name: "set_default_email_client",
+        description: "Set the default email client for subsequently added users; users may change it later. System administrator only.",
+        operationType: "write",
+        requiredScopes: [],
+        inputSchema: {
+            ...s.object("Default email client settings.", {
+                emailClient: s.stringEnum("Default email client for newly added users.", [
+                    "clientSoftware",
+                    "gmail",
+                    "office365",
+                ]),
+                encoding: s.stringEnum("Required only for clientSoftware.", ["sjis", "utf8", "iso2022jp"]),
+            }, { required: ["emailClient"] }),
+            allOf: [
+                {
+                    if: { properties: { emailClient: { const: "clientSoftware" } } },
+                    then: { required: ["encoding"] },
+                    else: { not: { required: ["encoding"] } },
+                },
+            ],
+        },
+        outputSchema: s.object("Organization default email client; null when not configured.", {
+            settings: s.nullable(s.object("Email client configuration.", {
+                emailClient: s.stringEnum("Default email client for newly added users.", [
+                    "clientSoftware",
+                    "gmail",
+                    "office365",
+                ]),
+                encoding: s.stringEnum("Required only for clientSoftware.", ["sjis", "utf8", "iso2022jp"]),
+            }, { additionalProperties: true, required: [] })),
+        }, { required: ["settings"] }),
+    }),
+];

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

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