@squadbase/vite-server 0.1.8 → 0.1.9-dev.3841401

package/dist/connectors/freshdesk.js

@@ -0,0 +1,842 @@
+// ../connectors/src/parameter-definition.ts
+var ParameterDefinition = class {
+  slug;
+  name;
+  description;
+  envVarBaseKey;
+  type;
+  secret;
+  required;
+  constructor(config) {
+    this.slug = config.slug;
+    this.name = config.name;
+    this.description = config.description;
+    this.envVarBaseKey = config.envVarBaseKey;
+    this.type = config.type;
+    this.secret = config.secret;
+    this.required = config.required;
+  }
+  /**
+   * Get the parameter value from a ConnectorConnectionObject.
+   */
+  getValue(connection2) {
+    const param = connection2.parameters.find(
+      (p) => p.parameterSlug === this.slug
+    );
+    if (!param || param.value == null) {
+      throw new Error(
+        `Parameter "${this.slug}" not found or has no value in connection "${connection2.id}"`
+      );
+    }
+    return param.value;
+  }
+  /**
+   * Try to get the parameter value. Returns undefined if not found (for optional params).
+   */
+  tryGetValue(connection2) {
+    const param = connection2.parameters.find(
+      (p) => p.parameterSlug === this.slug
+    );
+    if (!param || param.value == null) return void 0;
+    return param.value;
+  }
+};
+
+// ../connectors/src/connectors/freshdesk/parameters.ts
+var parameters = {
+  domain: new ParameterDefinition({
+    slug: "domain",
+    name: "Freshdesk Domain",
+    description: "Your Freshdesk subdomain (e.g. `acme` for `https://acme.freshdesk.com`). Provide just the subdomain without `https://` or the rest of the URL.",
+    envVarBaseKey: "FRESHDESK_DOMAIN",
+    type: "text",
+    secret: false,
+    required: true
+  }),
+  apiKey: new ParameterDefinition({
+    slug: "api-key",
+    name: "Freshdesk API Key",
+    description: "API key for Freshdesk. Find it in Freshdesk \u2192 Profile (top-right) \u2192 Profile Settings \u2192 API Key. The key is sent via HTTP Basic Auth (api-key as username, any value as password).",
+    envVarBaseKey: "FRESHDESK_API_KEY",
+    type: "text",
+    secret: true,
+    required: true
+  })
+};
+
+// ../connectors/src/connectors/freshdesk/sdk/index.ts
+function buildBaseUrl(domain) {
+  const trimmed = domain.trim().replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const subdomain = trimmed.split(".")[0];
+  return `https://${subdomain}.freshdesk.com/api/v2`;
+}
+function basicAuthHeader(apiKey) {
+  return `Basic ${Buffer.from(`${apiKey}:X`).toString("base64")}`;
+}
+function createClient(params) {
+  const apiKey = params[parameters.apiKey.slug];
+  const domain = params[parameters.domain.slug];
+  if (!apiKey) {
+    throw new Error(
+      `freshdesk: missing required parameter: ${parameters.apiKey.slug}`
+    );
+  }
+  if (!domain) {
+    throw new Error(
+      `freshdesk: missing required parameter: ${parameters.domain.slug}`
+    );
+  }
+  const baseUrl = buildBaseUrl(domain);
+  const auth = basicAuthHeader(apiKey);
+  function authHeaders(extra) {
+    const headers = new Headers(extra);
+    headers.set("Authorization", auth);
+    headers.set("Content-Type", "application/json");
+    headers.set("Accept", "application/json");
+    return headers;
+  }
+  async function assertOk(res, label) {
+    if (!res.ok) {
+      const body = await res.text().catch(() => "(unreadable body)");
+      throw new Error(
+        `freshdesk ${label}: ${res.status} ${res.statusText} \u2014 ${body}`
+      );
+    }
+  }
+  function buildQuery(base) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(base)) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+  }
+  return {
+    request(path2, init) {
+      const headers = new Headers(init?.headers);
+      headers.set("Authorization", auth);
+      if (!headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+      }
+      if (!headers.has("Accept")) {
+        headers.set("Accept", "application/json");
+      }
+      return fetch(`${baseUrl}${path2}`, { ...init, headers });
+    },
+    async listTickets(options) {
+      const qs = buildQuery({
+        page: options?.page,
+        per_page: options?.per_page,
+        include: options?.include,
+        updated_since: options?.updated_since,
+        order_by: options?.order_by,
+        order_type: options?.order_type,
+        filter: options?.filter
+      });
+      const res = await fetch(`${baseUrl}/tickets${qs}`, {
+        method: "GET",
+        headers: authHeaders()
+      });
+      await assertOk(res, "listTickets");
+      return await res.json();
+    },
+    async getTicket(ticketId, options) {
+      const qs = buildQuery({ include: options?.include });
+      const res = await fetch(
+        `${baseUrl}/tickets/${encodeURIComponent(String(ticketId))}${qs}`,
+        { method: "GET", headers: authHeaders() }
+      );
+      await assertOk(res, "getTicket");
+      return await res.json();
+    },
+    async createTicket(ticketData) {
+      const res = await fetch(`${baseUrl}/tickets`, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify(ticketData)
+      });
+      await assertOk(res, "createTicket");
+      return await res.json();
+    },
+    async updateTicket(ticketId, ticketData) {
+      const res = await fetch(
+        `${baseUrl}/tickets/${encodeURIComponent(String(ticketId))}`,
+        {
+          method: "PUT",
+          headers: authHeaders(),
+          body: JSON.stringify(ticketData)
+        }
+      );
+      await assertOk(res, "updateTicket");
+      return await res.json();
+    },
+    async searchTickets(query) {
+      const qs = `?query=${encodeURIComponent(`"${query}"`)}`;
+      const res = await fetch(`${baseUrl}/search/tickets${qs}`, {
+        method: "GET",
+        headers: authHeaders()
+      });
+      await assertOk(res, "searchTickets");
+      return await res.json();
+    },
+    async listContacts(options) {
+      const qs = buildQuery({
+        page: options?.page,
+        per_page: options?.per_page,
+        email: options?.email,
+        mobile: options?.mobile,
+        phone: options?.phone,
+        company_id: options?.company_id,
+        state: options?.state
+      });
+      const res = await fetch(`${baseUrl}/contacts${qs}`, {
+        method: "GET",
+        headers: authHeaders()
+      });
+      await assertOk(res, "listContacts");
+      return await res.json();
+    },
+    async listCompanies(options) {
+      const qs = buildQuery({
+        page: options?.page,
+        per_page: options?.per_page
+      });
+      const res = await fetch(`${baseUrl}/companies${qs}`, {
+        method: "GET",
+        headers: authHeaders()
+      });
+      await assertOk(res, "listCompanies");
+      return await res.json();
+    },
+    async listAgents(options) {
+      const qs = buildQuery({
+        page: options?.page,
+        per_page: options?.per_page,
+        email: options?.email,
+        state: options?.state
+      });
+      const res = await fetch(`${baseUrl}/agents${qs}`, {
+        method: "GET",
+        headers: authHeaders()
+      });
+      await assertOk(res, "listAgents");
+      return await res.json();
+    }
+  };
+}
+
+// ../connectors/src/connector-onboarding.ts
+var ConnectorOnboarding = class {
+  /** Phase 1: Connection setup instructions (optional — some connectors don't need this) */
+  connectionSetupInstructions;
+  /** Phase 2: Data overview instructions */
+  dataOverviewInstructions;
+  constructor(config) {
+    this.connectionSetupInstructions = config.connectionSetupInstructions;
+    this.dataOverviewInstructions = config.dataOverviewInstructions;
+  }
+  getConnectionSetupPrompt(language) {
+    return this.connectionSetupInstructions?.[language] ?? null;
+  }
+  getDataOverviewInstructions(language) {
+    return this.dataOverviewInstructions[language];
+  }
+};
+
+// ../connectors/src/connector-tool.ts
+var ConnectorTool = class {
+  name;
+  description;
+  inputSchema;
+  outputSchema;
+  _execute;
+  constructor(config) {
+    this.name = config.name;
+    this.description = config.description;
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this._execute = config.execute;
+  }
+  createTool(connections, config) {
+    return {
+      description: this.description,
+      inputSchema: this.inputSchema,
+      outputSchema: this.outputSchema,
+      execute: (input) => this._execute(input, connections, config)
+    };
+  }
+};
+
+// ../connectors/src/connector-plugin.ts
+var ConnectorPlugin = class _ConnectorPlugin {
+  slug;
+  authType;
+  name;
+  description;
+  iconUrl;
+  parameters;
+  releaseFlag;
+  proxyPolicy;
+  experimentalAttributes;
+  categories;
+  onboarding;
+  systemPrompt;
+  tools;
+  query;
+  checkConnection;
+  constructor(config) {
+    this.slug = config.slug;
+    this.authType = config.authType;
+    this.name = config.name;
+    this.description = config.description;
+    this.iconUrl = config.iconUrl;
+    this.parameters = config.parameters;
+    this.releaseFlag = config.releaseFlag;
+    this.proxyPolicy = config.proxyPolicy;
+    this.experimentalAttributes = config.experimentalAttributes;
+    this.categories = config.categories ?? [];
+    this.onboarding = config.onboarding;
+    this.systemPrompt = config.systemPrompt;
+    this.tools = config.tools;
+    this.query = config.query;
+    this.checkConnection = config.checkConnection;
+  }
+  get connectorKey() {
+    return _ConnectorPlugin.deriveKey(this.slug, this.authType);
+  }
+  /**
+   * Create tools for connections that belong to this connector.
+   * Filters connections by connectorKey internally.
+   * Returns tools keyed as `${connectorKey}_${toolName}`.
+   */
+  createTools(connections, config, opts) {
+    const myConnections = connections.filter(
+      (c) => _ConnectorPlugin.deriveKey(c.connector.slug, c.connector.authType) === this.connectorKey
+    );
+    const result = {};
+    for (const t of Object.values(this.tools)) {
+      const tool = t.createTool(myConnections, config);
+      const originalToModelOutput = tool.toModelOutput;
+      result[`${this.connectorKey}_${t.name}`] = {
+        ...tool,
+        toModelOutput: async (options) => {
+          if (!originalToModelOutput) {
+            return opts.truncateOutput(options.output);
+          }
+          const modelOutput = await originalToModelOutput(options);
+          if (modelOutput.type === "text" || modelOutput.type === "json") {
+            return opts.truncateOutput(modelOutput.value);
+          }
+          return modelOutput;
+        }
+      };
+    }
+    return result;
+  }
+  static deriveKey(slug, authType) {
+    if (authType) return `${slug}-${authType}`;
+    const LEGACY_NULL_AUTH_TYPE_MAP = {
+      // user-password
+      "postgresql": "user-password",
+      "mysql": "user-password",
+      "clickhouse": "user-password",
+      "kintone": "user-password",
+      "squadbase-db": "user-password",
+      // service-account
+      "snowflake": "service-account",
+      "bigquery": "service-account",
+      "google-analytics": "service-account",
+      "google-calendar": "service-account",
+      "aws-athena": "service-account",
+      "redshift": "service-account",
+      // api-key
+      "databricks": "api-key",
+      "dbt": "api-key",
+      "airtable": "api-key",
+      "openai": "api-key",
+      "gemini": "api-key",
+      "anthropic": "api-key",
+      "wix-store": "api-key"
+    };
+    const fallbackAuthType = LEGACY_NULL_AUTH_TYPE_MAP[slug];
+    if (fallbackAuthType) return `${slug}-${fallbackAuthType}`;
+    return slug;
+  }
+};
+
+// ../connectors/src/auth-types.ts
+var AUTH_TYPES = {
+  OAUTH: "oauth",
+  API_KEY: "api-key",
+  JWT: "jwt",
+  SERVICE_ACCOUNT: "service-account",
+  PAT: "pat",
+  USER_PASSWORD: "user-password"
+};
+
+// ../connectors/src/lib/normalize-path.ts
+function normalizeRequestPath(path2, basePathSegment) {
+  let p = path2.trim();
+  if (!p.startsWith("/")) p = "/" + p;
+  if (p === basePathSegment || p.startsWith(basePathSegment + "/")) {
+    p = p.slice(basePathSegment.length) || "/";
+  }
+  return p;
+}
+
+// ../connectors/src/connectors/freshdesk/setup.ts
+var freshdeskOnboarding = new ConnectorOnboarding({
+  dataOverviewInstructions: {
+    en: `1. Call freshdesk_request with GET /agents/me to confirm credentials.
+2. Call freshdesk_request with GET /tickets?per_page=10&order_by=created_at&order_type=desc to sample recent tickets. Each ticket carries \`status\`, \`priority\`, \`source\`, \`requester_id\`, \`responder_id\`, and \`created_at\`.
+3. Call GET /contacts?per_page=10 to sample contacts (end users) and GET /companies?per_page=10 for companies.
+4. To enumerate agents and groups, call GET /agents and GET /groups.
+5. Pagination is page-based with \`page\` (1-indexed) and \`per_page\` (max 100). The \`Link\` response header carries the next-page URL when more results exist.`,
+    ja: `1. freshdesk_request \u3067 GET /agents/me \u3092\u547C\u3073\u51FA\u3057\u3001\u8A8D\u8A3C\u60C5\u5831\u3092\u78BA\u8A8D\u3057\u307E\u3059\u3002
+2. freshdesk_request \u3067 GET /tickets?per_page=10&order_by=created_at&order_type=desc \u3092\u547C\u3073\u51FA\u3057\u3066\u6700\u8FD1\u306E\u30C1\u30B1\u30C3\u30C8\u3092\u30B5\u30F3\u30D7\u30EA\u30F3\u30B0\u3057\u307E\u3059\u3002\u5404\u30C1\u30B1\u30C3\u30C8\u306B\u306F \`status\`, \`priority\`, \`source\`, \`requester_id\`, \`responder_id\`, \`created_at\` \u306A\u3069\u304C\u542B\u307E\u308C\u307E\u3059\u3002
+3. GET /contacts?per_page=10 \u3067\u9023\u7D61\u5148\uFF08\u30A8\u30F3\u30C9\u30E6\u30FC\u30B6\u30FC\uFF09\u3001GET /companies?per_page=10 \u3067\u4F1A\u793E\u60C5\u5831\u3092\u30B5\u30F3\u30D7\u30EA\u30F3\u30B0\u3057\u307E\u3059\u3002
+4. \u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u3084\u30B0\u30EB\u30FC\u30D7\u306F GET /agents\u3001GET /groups \u3067\u53D6\u5F97\u3057\u307E\u3059\u3002
+5. \u30DA\u30FC\u30B8\u30CD\u30FC\u30B7\u30E7\u30F3\u306F1\u59CB\u307E\u308A\u306E \`page\` \u3068 \`per_page\`\uFF08\u6700\u5927100\uFF09\u3002\u6B21\u30DA\u30FC\u30B8\u304C\u5B58\u5728\u3059\u308B\u5834\u5408\u306F \`Link\` \u30EC\u30B9\u30DD\u30F3\u30B9\u30D8\u30C3\u30C0\u306B\u6B21URL\u304C\u542B\u307E\u308C\u307E\u3059\u3002`
+  }
+});
+
+// ../connectors/src/connectors/freshdesk/tools/request.ts
+import { z } from "zod";
+var BASE_PATH_SEGMENT = "/api/v2";
+var REQUEST_TIMEOUT_MS = 6e4;
+function buildBaseUrl2(domain) {
+  const trimmed = domain.trim().replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const subdomain = trimmed.split(".")[0];
+  return `https://${subdomain}.freshdesk.com${BASE_PATH_SEGMENT}`;
+}
+function basicAuthHeader2(apiKey) {
+  return `Basic ${Buffer.from(`${apiKey}:X`).toString("base64")}`;
+}
+var inputSchema = z.object({
+  toolUseIntent: z.string().optional().describe(
+    "Brief description of what you intend to accomplish with this tool call"
+  ),
+  connectionId: z.string().describe("ID of the Freshdesk connection to use"),
+  method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe(
+    "HTTP method. GET for reading resources, POST for creating, PUT for updating, DELETE for removing."
+  ),
+  path: z.string().describe(
+    "API path (e.g., '/tickets', '/tickets/123', '/contacts'). Append query parameters such as '?per_page=100&page=1&order_by=created_at&order_type=desc'."
+  ),
+  body: z.record(z.string(), z.unknown()).optional().describe(
+    'Request body (JSON) for POST/PUT requests. Example creating a ticket: { "subject": "...", "description": "...", "email": "...", "priority": 2, "status": 2, "source": 1 }.'
+  )
+});
+var outputSchema = z.discriminatedUnion("success", [
+  z.object({
+    success: z.literal(true),
+    status: z.number(),
+    data: z.union([
+      z.record(z.string(), z.unknown()),
+      z.array(z.unknown())
+    ])
+  }),
+  z.object({
+    success: z.literal(false),
+    error: z.string()
+  })
+]);
+var requestTool = new ConnectorTool({
+  name: "request",
+  description: `Send authenticated requests to the Freshdesk REST API v2.
+Authentication is HTTP Basic Auth using the API key as the username (handled automatically).
+Provide the API path relative to the base URL (https://<domain>.freshdesk.com/api/v2).
+
+Common endpoints:
+- GET /tickets \u2014 List tickets (paginated). Use ?include=requester,company,stats to enrich responses.
+- GET /tickets/{id} \u2014 Get a ticket
+- POST /tickets \u2014 Create a ticket (body: { subject, description, email, priority, status, source })
+- PUT /tickets/{id} \u2014 Update a ticket
+- GET /tickets/{id}/conversations \u2014 Replies and notes on a ticket
+- POST /tickets/{id}/reply \u2014 Reply to a ticket
+- POST /tickets/{id}/notes \u2014 Add a private note
+- GET /contacts \u2014 List contacts (end users)
+- GET /companies \u2014 List companies
+- GET /agents \u2014 List agents
+- GET /agents/me \u2014 Get the calling agent (useful as auth probe)
+- GET /groups \u2014 List agent groups
+- GET /solutions/categories \u2014 Knowledge base categories
+- GET /search/tickets?query="..." \u2014 Filter tickets (advanced search)
+
+Pagination: ?page=1&per_page=100 (per_page max 100). Inspect the \`Link\` response header for the next-page URL.
+
+Field codes (tickets):
+- priority: 1 Low, 2 Medium, 3 High, 4 Urgent
+- status: 2 Open, 3 Pending, 4 Resolved, 5 Closed
+- source: 1 Email, 2 Portal, 3 Phone, 7 Chat, 9 Feedback widget, 10 Outbound email`,
+  inputSchema,
+  outputSchema,
+  async execute({ connectionId, method, path: path2, body }, connections) {
+    const connection2 = connections.find((c) => c.id === connectionId);
+    if (!connection2) {
+      return {
+        success: false,
+        error: `Connection ${connectionId} not found`
+      };
+    }
+    console.log(
+      `[connector-request] freshdesk/${connection2.name}: ${method} ${path2}`
+    );
+    try {
+      const apiKey = parameters.apiKey.getValue(connection2);
+      const domain = parameters.domain.getValue(connection2);
+      const baseUrl = buildBaseUrl2(domain);
+      const normalizedPath = normalizeRequestPath(path2, BASE_PATH_SEGMENT);
+      const url = `${baseUrl}${normalizedPath}`;
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: {
+            Authorization: basicAuthHeader2(apiKey),
+            "Content-Type": "application/json",
+            Accept: "application/json"
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        const text = await response.text();
+        const data = text ? JSON.parse(text) : {};
+        if (!response.ok) {
+          const errObj = !Array.isArray(data) ? data : {};
+          const description = typeof errObj.description === "string" && errObj.description || typeof errObj.message === "string" && errObj.message;
+          const errors = errObj.errors;
+          const fieldDetail = Array.isArray(errors) && errors.length > 0 ? ` \u2014 ${errors[0]?.message ?? ""}` : "";
+          const errorMessage = description ? `${description}${fieldDetail}` : `HTTP ${response.status} ${response.statusText}`;
+          return { success: false, error: String(errorMessage) };
+        }
+        return { success: true, status: response.status, data };
+      } finally {
+        clearTimeout(timeout);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: msg };
+    }
+  }
+});
+
+// ../connectors/src/connectors/freshdesk/index.ts
+var tools = { request: requestTool };
+var freshdeskConnector = new ConnectorPlugin({
+  slug: "freshdesk",
+  authType: AUTH_TYPES.API_KEY,
+  name: "Freshdesk",
+  description: "Connect to Freshdesk for customer support ticket, contact, and company data via API key.",
+  iconUrl: "https://images.ctfassets.net/9ncizv60xc5y/1PSjIfQJgTYmiWriNTx4uE/26905f4120713bda0afd0b23d02a154e/freshdesk-icon.png",
+  parameters,
+  releaseFlag: { dev1: true, dev2: true, prod: true },
+  categories: ["crm"],
+  onboarding: freshdeskOnboarding,
+  systemPrompt: {
+    en: `### Tools
+
+- \`freshdesk_request\`: The only way to call the Freshdesk REST API v2. Use it to list tickets, contacts, companies, agents, groups, and more. Authentication (HTTP Basic Auth using the API key as username) and the base URL (https://<domain>.freshdesk.com/api/v2) are configured automatically.
+
+### Business Logic
+
+The business logic type for this connector is "typescript". Use the connector SDK in your handler. Do NOT read credentials from environment variables.
+
+SDK methods (client created via \`connection(connectionId)\`):
+- \`client.request(path, init?)\` \u2014 low-level authenticated fetch
+- \`client.listTickets(options?)\` \u2014 list tickets (paginated)
+- \`client.getTicket(ticketId, options?)\` \u2014 get a single ticket
+- \`client.createTicket(ticketData)\` \u2014 create a ticket
+- \`client.updateTicket(ticketId, ticketData)\` \u2014 update a ticket
+- \`client.searchTickets(query)\` \u2014 advanced search (e.g. \`status:2 AND priority:>2\`)
+- \`client.listContacts(options?)\` \u2014 list contacts
+- \`client.listCompanies(options?)\` \u2014 list companies
+- \`client.listAgents(options?)\` \u2014 list agents
+
+\`\`\`ts
+import type { Context } from "hono";
+import { connection } from "@squadbase/vite-server/connectors/freshdesk";
+
+const fd = connection("<connectionId>");
+
+export default async function handler(c: Context) {
+  const tickets = await fd.listTickets({
+    per_page: 100,
+    include: "requester,company",
+    order_by: "created_at",
+    order_type: "desc",
+  });
+  return c.json({ tickets });
+}
+\`\`\`
+
+### Freshdesk REST API v2 Reference
+
+- Base URL: \`https://<domain>.freshdesk.com/api/v2\`
+- Authentication: HTTP Basic Auth (\`<API_KEY>:X\`, base64-encoded; the password is ignored).
+- Pagination: 1-indexed \`page\` + \`per_page\` (max 100). Tickets max 300 pages historically \u2014 use \`updated_since\` or \`/search/tickets\` for larger windows.
+- Sorting: \`order_by\` \u2208 { created_at, updated_at, due_by, status }, \`order_type\` \u2208 { asc, desc }.
+
+#### Resource Endpoints
+
+**Tickets**
+- GET \`/tickets\` \u2014 List tickets (use \`include=requester,company,stats\` to enrich)
+- GET \`/tickets/{id}\` \u2014 Get a ticket
+- POST \`/tickets\` \u2014 Create a ticket
+- PUT \`/tickets/{id}\` \u2014 Update a ticket
+- DELETE \`/tickets/{id}\` \u2014 Soft-delete a ticket
+- GET \`/tickets/{id}/conversations\` \u2014 Replies and notes
+- POST \`/tickets/{id}/reply\` \u2014 Reply to a ticket
+- POST \`/tickets/{id}/notes\` \u2014 Add a private/public note
+- GET \`/search/tickets?query="..."\` \u2014 Advanced search (e.g. \`"priority:>2 AND status:2"\`)
+
+**Users & Companies**
+- GET \`/contacts\` \u2014 List end-user contacts
+- GET \`/contacts/{id}\` \u2014 Get a contact
+- POST \`/contacts\` \u2014 Create a contact
+- PUT \`/contacts/{id}\` \u2014 Update a contact
+- GET \`/companies\` \u2014 List companies
+- POST \`/companies\` \u2014 Create a company
+- GET \`/agents\` \u2014 List agents
+- GET \`/agents/me\` \u2014 Calling agent (auth probe)
+- GET \`/groups\` \u2014 Agent groups
+
+**Knowledge Base**
+- GET \`/solutions/categories\` \u2014 Categories
+- GET \`/solutions/categories/{id}/folders\` \u2014 Folders in a category
+- GET \`/solutions/folders/{id}/articles\` \u2014 Articles in a folder
+
+#### Field codes (tickets)
+
+- \`priority\`: 1=Low, 2=Medium, 3=High, 4=Urgent
+- \`status\`: 2=Open, 3=Pending, 4=Resolved, 5=Closed
+- \`source\`: 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback widget, 10=Outbound email`,
+    ja: `### \u30C4\u30FC\u30EB
+
+- \`freshdesk_request\`: Freshdesk REST API v2 \u3092\u547C\u3073\u51FA\u3059\u552F\u4E00\u306E\u624B\u6BB5\u3067\u3059\u3002\u30C1\u30B1\u30C3\u30C8\u3001\u9023\u7D61\u5148\u3001\u4F1A\u793E\u3001\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u3001\u30B0\u30EB\u30FC\u30D7\u306A\u3069\u306E\u53D6\u5F97\u30FB\u66F4\u65B0\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002\u8A8D\u8A3C\uFF08API \u30AD\u30FC\u3092\u30E6\u30FC\u30B6\u30FC\u540D\u3068\u3057\u305F HTTP Basic Auth\uFF09\u3068\u30D9\u30FC\u30B9URL\uFF08https://<\u30C9\u30E1\u30A4\u30F3>.freshdesk.com/api/v2\uFF09\u306F\u81EA\u52D5\u3067\u8A2D\u5B9A\u3055\u308C\u307E\u3059\u3002
+
+### Business Logic
+
+\u3053\u306E\u30B3\u30CD\u30AF\u30BF\u306E\u30D3\u30B8\u30CD\u30B9\u30ED\u30B8\u30C3\u30AF\u30BF\u30A4\u30D7\u306F "typescript" \u3067\u3059\u3002\u30CF\u30F3\u30C9\u30E9\u5185\u3067\u306F\u30B3\u30CD\u30AF\u30BFSDK\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u74B0\u5883\u5909\u6570\u304B\u3089\u8A8D\u8A3C\u60C5\u5831\u3092\u8AAD\u307F\u53D6\u3089\u306A\u3044\u3067\u304F\u3060\u3055\u3044\u3002
+
+SDK\u30E1\u30BD\u30C3\u30C9 (\`connection(connectionId)\` \u3067\u4F5C\u6210\u3057\u305F\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8):
+- \`client.request(path, init?)\` \u2014 \u4F4E\u30EC\u30D9\u30EB\u306E\u8A8D\u8A3C\u4ED8\u304Dfetch
+- \`client.listTickets(options?)\` \u2014 \u30C1\u30B1\u30C3\u30C8\u4E00\u89A7\uFF08\u30DA\u30FC\u30B8\u30F3\u30B0\uFF09
+- \`client.getTicket(ticketId, options?)\` \u2014 \u5358\u4E00\u30C1\u30B1\u30C3\u30C8\u306E\u53D6\u5F97
+- \`client.createTicket(ticketData)\` \u2014 \u30C1\u30B1\u30C3\u30C8\u306E\u4F5C\u6210
+- \`client.updateTicket(ticketId, ticketData)\` \u2014 \u30C1\u30B1\u30C3\u30C8\u306E\u66F4\u65B0
+- \`client.searchTickets(query)\` \u2014 \u9AD8\u5EA6\u306A\u691C\u7D22\uFF08\u4F8B: \`status:2 AND priority:>2\`\uFF09
+- \`client.listContacts(options?)\` \u2014 \u9023\u7D61\u5148\u4E00\u89A7
+- \`client.listCompanies(options?)\` \u2014 \u4F1A\u793E\u4E00\u89A7
+- \`client.listAgents(options?)\` \u2014 \u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u4E00\u89A7
+
+\`\`\`ts
+import type { Context } from "hono";
+import { connection } from "@squadbase/vite-server/connectors/freshdesk";
+
+const fd = connection("<connectionId>");
+
+export default async function handler(c: Context) {
+  const tickets = await fd.listTickets({
+    per_page: 100,
+    include: "requester,company",
+    order_by: "created_at",
+    order_type: "desc",
+  });
+  return c.json({ tickets });
+}
+\`\`\`
+
+### Freshdesk REST API v2 \u30EA\u30D5\u30A1\u30EC\u30F3\u30B9
+
+- \u30D9\u30FC\u30B9URL: \`https://<\u30C9\u30E1\u30A4\u30F3>.freshdesk.com/api/v2\`
+- \u8A8D\u8A3C: HTTP Basic Auth\uFF08\`<API_KEY>:X\` \u3092 base64 \u30A8\u30F3\u30B3\u30FC\u30C9\u3001\u30D1\u30B9\u30EF\u30FC\u30C9\u90E8\u306F\u7121\u8996\u3055\u308C\u307E\u3059\uFF09
+- \u30DA\u30FC\u30B8\u30CD\u30FC\u30B7\u30E7\u30F3: 1\u59CB\u307E\u308A\u306E \`page\` \u3068 \`per_page\`\uFF08\u6700\u5927100\uFF09\u3002\u30C1\u30B1\u30C3\u30C8\u4E00\u89A7\u306F\u6700\u5927300\u30DA\u30FC\u30B8\u7A0B\u5EA6\u306E\u5C65\u6B74\u5236\u9650\u304C\u3042\u308B\u305F\u3081\u3001\u3088\u308A\u5E83\u3044\u671F\u9593\u3092\u53D6\u308A\u305F\u3044\u5834\u5408\u306F \`updated_since\` \u304B \`/search/tickets\` \u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+- \u30BD\u30FC\u30C8: \`order_by\` \u2208 { created_at, updated_at, due_by, status }, \`order_type\` \u2208 { asc, desc }\u3002
+
+#### \u30EA\u30BD\u30FC\u30B9\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8
+
+**\u30C1\u30B1\u30C3\u30C8**
+- GET \`/tickets\` \u2014 \u30C1\u30B1\u30C3\u30C8\u4E00\u89A7\uFF08\`include=requester,company,stats\` \u3067\u95A2\u9023\u60C5\u5831\u3092\u5C55\u958B\u53EF\u80FD\uFF09
+- GET \`/tickets/{id}\` \u2014 \u30C1\u30B1\u30C3\u30C8\u306E\u53D6\u5F97
+- POST \`/tickets\` \u2014 \u30C1\u30B1\u30C3\u30C8\u306E\u4F5C\u6210
+- PUT \`/tickets/{id}\` \u2014 \u30C1\u30B1\u30C3\u30C8\u306E\u66F4\u65B0
+- DELETE \`/tickets/{id}\` \u2014 \u30C1\u30B1\u30C3\u30C8\u306E\u8AD6\u7406\u524A\u9664
+- GET \`/tickets/{id}/conversations\` \u2014 \u8FD4\u4FE1\u30FB\u30CE\u30FC\u30C8\u4E00\u89A7
+- POST \`/tickets/{id}/reply\` \u2014 \u30C1\u30B1\u30C3\u30C8\u3078\u306E\u8FD4\u4FE1
+- POST \`/tickets/{id}/notes\` \u2014 \u30D7\u30E9\u30A4\u30D9\u30FC\u30C8/\u30D1\u30D6\u30EA\u30C3\u30AF\u30CE\u30FC\u30C8\u306E\u8FFD\u52A0
+- GET \`/search/tickets?query="..."\` \u2014 \u9AD8\u5EA6\u306A\u691C\u7D22\uFF08\u4F8B: \`"priority:>2 AND status:2"\`\uFF09
+
+**\u30E6\u30FC\u30B6\u30FC & \u4F1A\u793E**
+- GET \`/contacts\` \u2014 \u30A8\u30F3\u30C9\u30E6\u30FC\u30B6\u30FC\u9023\u7D61\u5148\u306E\u4E00\u89A7
+- GET \`/contacts/{id}\` \u2014 \u9023\u7D61\u5148\u306E\u53D6\u5F97
+- POST \`/contacts\` \u2014 \u9023\u7D61\u5148\u306E\u4F5C\u6210
+- PUT \`/contacts/{id}\` \u2014 \u9023\u7D61\u5148\u306E\u66F4\u65B0
+- GET \`/companies\` \u2014 \u4F1A\u793E\u4E00\u89A7
+- POST \`/companies\` \u2014 \u4F1A\u793E\u306E\u4F5C\u6210
+- GET \`/agents\` \u2014 \u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u4E00\u89A7
+- GET \`/agents/me\` \u2014 \u8A8D\u8A3C\u4E2D\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u306E\u53D6\u5F97
+- GET \`/groups\` \u2014 \u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u30B0\u30EB\u30FC\u30D7
+
+**\u30CA\u30EC\u30C3\u30B8\u30D9\u30FC\u30B9**
+- GET \`/solutions/categories\` \u2014 \u30AB\u30C6\u30B4\u30EA
+- GET \`/solutions/categories/{id}/folders\` \u2014 \u30AB\u30C6\u30B4\u30EA\u5185\u306E\u30D5\u30A9\u30EB\u30C0
+- GET \`/solutions/folders/{id}/articles\` \u2014 \u30D5\u30A9\u30EB\u30C0\u5185\u306E\u8A18\u4E8B
+
+#### \u30D5\u30A3\u30FC\u30EB\u30C9\u30B3\u30FC\u30C9\uFF08\u30C1\u30B1\u30C3\u30C8\uFF09
+
+- \`priority\`: 1=Low, 2=Medium, 3=High, 4=Urgent
+- \`status\`: 2=Open, 3=Pending, 4=Resolved, 5=Closed
+- \`source\`: 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback widget, 10=Outbound email`
+  },
+  tools
+});
+
+// src/connectors/create-connector-sdk.ts
+import { readFileSync } from "fs";
+import path from "path";
+
+// src/connector-client/env.ts
+function resolveEnvVar(entry, key, connectionId) {
+  const envVarName = entry.envVars[key];
+  if (!envVarName) {
+    throw new Error(`Connection "${connectionId}" is missing envVars mapping for key "${key}"`);
+  }
+  const value = process.env[envVarName];
+  if (!value) {
+    throw new Error(`Environment variable "${envVarName}" (for connection "${connectionId}", key "${key}") is not set`);
+  }
+  return value;
+}
+function resolveEnvVarOptional(entry, key) {
+  const envVarName = entry.envVars[key];
+  if (!envVarName) return void 0;
+  return process.env[envVarName] || void 0;
+}
+
+// src/connector-client/proxy-fetch.ts
+import { getContext } from "hono/context-storage";
+import { getCookie } from "hono/cookie";
+var APP_SESSION_COOKIE_NAME = "__Host-squadbase-session";
+function normalizeHeaders(input) {
+  const out = {};
+  if (!input) return out;
+  new Headers(input).forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+function createSandboxProxyFetch(connectionId) {
+  return async (input, init) => {
+    const token = process.env.INTERNAL_SQUADBASE_OAUTH_MACHINE_CREDENTIAL;
+    const sandboxId = process.env.INTERNAL_SQUADBASE_SANDBOX_ID;
+    if (!token || !sandboxId) {
+      throw new Error(
+        "Connection proxy is not configured. Please check your deployment settings."
+      );
+    }
+    const originalUrl = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const originalMethod = init?.method ?? "GET";
+    const originalBody = init?.body ? JSON.parse(init.body) : void 0;
+    const baseDomain = process.env["SQUADBASE_PREVIEW_BASE_DOMAIN"] ?? "preview.app.squadbase.dev";
+    const proxyUrl = `https://${sandboxId}.${baseDomain}/_sqcore/connections/${connectionId}/request`;
+    return fetch(proxyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify({
+        url: originalUrl,
+        method: originalMethod,
+        headers: normalizeHeaders(init?.headers),
+        body: originalBody
+      })
+    });
+  };
+}
+function createDeployedAppProxyFetch(connectionId) {
+  const projectId = process.env["SQUADBASE_PROJECT_ID"];
+  if (!projectId) {
+    throw new Error(
+      "Connection proxy is not configured. Please check your deployment settings."
+    );
+  }
+  const baseDomain = process.env["SQUADBASE_APP_BASE_DOMAIN"] ?? "squadbase.app";
+  const proxyUrl = `https://${projectId}.${baseDomain}/_sqcore/connections/${connectionId}/request`;
+  return async (input, init) => {
+    const originalUrl = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const originalMethod = init?.method ?? "GET";
+    const originalBody = init?.body ? JSON.parse(init.body) : void 0;
+    const c = getContext();
+    const appSession = getCookie(c, APP_SESSION_COOKIE_NAME);
+    if (!appSession) {
+      throw new Error(
+        "No authentication method available for connection proxy."
+      );
+    }
+    return fetch(proxyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${appSession}`
+      },
+      body: JSON.stringify({
+        url: originalUrl,
+        method: originalMethod,
+        headers: normalizeHeaders(init?.headers),
+        body: originalBody
+      })
+    });
+  };
+}
+function createProxyFetch(connectionId) {
+  if (process.env.INTERNAL_SQUADBASE_SANDBOX_ID) {
+    return createSandboxProxyFetch(connectionId);
+  }
+  return createDeployedAppProxyFetch(connectionId);
+}
+
+// src/connectors/create-connector-sdk.ts
+function loadConnectionsSync() {
+  const filePath = process.env.CONNECTIONS_PATH ?? path.join(process.cwd(), ".squadbase/connections.json");
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function createConnectorSdk(plugin, createClient2) {
+  return (connectionId) => {
+    const connections = loadConnectionsSync();
+    const entry = connections[connectionId];
+    if (!entry) {
+      throw new Error(
+        `Connection "${connectionId}" not found in .squadbase/connections.json`
+      );
+    }
+    if (entry.connector.slug !== plugin.slug) {
+      throw new Error(
+        `Connection "${connectionId}" is not a ${plugin.slug} connection (got "${entry.connector.slug}")`
+      );
+    }
+    const params = {};
+    for (const param of Object.values(plugin.parameters)) {
+      if (param.required) {
+        params[param.slug] = resolveEnvVar(entry, param.slug, connectionId);
+      } else {
+        const val = resolveEnvVarOptional(entry, param.slug);
+        if (val !== void 0) params[param.slug] = val;
+      }
+    }
+    return createClient2(params, createProxyFetch(connectionId));
+  };
+}
+
+// src/connectors/entries/freshdesk.ts
+var connection = createConnectorSdk(freshdeskConnector, createClient);
+export {
+  connection
+};