@hasna/connectors 1.4.4 → 1.4.6

package/dist/sdk/index.js

@@ -0,0 +1,508 @@
+// @bun
+var __require = import.meta.require;
+
+// src/sdk/index.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var LOCAL_SERVE_TOKEN_ENV = "HASNA_CONNECTORS_SERVE_TOKEN";
+var LOCAL_SERVE_TOKEN_HEADER = "X-Connectors-Token";
+function resolveLocalServeToken(env = typeof process !== "undefined" ? process.env : {}) {
+  const fromEnv = env[LOCAL_SERVE_TOKEN_ENV]?.trim();
+  if (fromEnv)
+    return fromEnv;
+  const exact = env["HASNA_CONNECTORS_DIR"]?.trim();
+  const home = env["HOME"] || env["USERPROFILE"] || (typeof process !== "undefined" ? homedir() : "");
+  const connectorsHome = exact ? exact : join(home, ".hasna", "connectors");
+  try {
+    const value = readFileSync(join(connectorsHome, "serve-token"), "utf-8").trim();
+    return value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+class HostedConnectorsError extends Error {
+  status;
+  code;
+  payload;
+  requestId;
+  constructor(message, options) {
+    super(message);
+    this.name = "HostedConnectorsError";
+    this.status = options.status;
+    this.code = options.code;
+    this.payload = options.payload;
+    this.requestId = options.requestId;
+  }
+}
+function normalizeConnectorSlug(slug) {
+  let normalized = slug.trim().toLowerCase();
+  if (normalized.startsWith("@hasna/"))
+    normalized = normalized.slice("@hasna/".length);
+  if (normalized.startsWith("connect-"))
+    normalized = normalized.slice("connect-".length);
+  if (!normalized)
+    throw new Error("connector slug is required");
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) {
+    throw new Error(`invalid connector slug: ${slug}`);
+  }
+  return normalized;
+}
+function normalizeOperationKey(value) {
+  const [connectorSlug, ...rest] = value.split(":");
+  return rest.length === 0 ? normalizeConnectorSlug(connectorSlug) : `${normalizeConnectorSlug(connectorSlug)}:${rest.join(":")}`;
+}
+function normalizePolicyConnectorLists(input) {
+  const copy = { ...input };
+  for (const key of ["connectorAllowlist", "connectorBlocklist"]) {
+    if (Array.isArray(copy[key])) {
+      copy[key] = copy[key].map((value) => typeof value === "string" ? normalizeConnectorSlug(value) : value);
+    }
+  }
+  for (const key of ["operationAllowlist", "operationDenylist", "approvalRequiredOperations"]) {
+    if (Array.isArray(copy[key])) {
+      copy[key] = copy[key].map((value) => typeof value === "string" ? normalizeOperationKey(value) : value);
+    }
+  }
+  return copy;
+}
+
+class LocalConnectorsClient {
+  baseUrl;
+  connectorsDir;
+  token;
+  constructor(options = {}) {
+    this.baseUrl = (options.serverUrl ?? "http://localhost:9876").replace(/\/$/, "");
+    this.connectorsDir = options.connectorsDir ?? ".connectors";
+    this.token = options.token?.trim() || resolveLocalServeToken(options.env);
+  }
+  get hasToken() {
+    return this.token !== null;
+  }
+  async request(path, options) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = new Headers({ "Content-Type": "application/json" });
+    if (this.token) {
+      headers.set("Authorization", `Bearer ${this.token}`);
+      headers.set(LOCAL_SERVE_TOKEN_HEADER, this.token);
+    }
+    if (options?.headers) {
+      new Headers(options.headers).forEach((value, key) => headers.set(key, value));
+    }
+    const res = await fetch(url, {
+      ...options,
+      headers
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      const err = data;
+      throw new Error(err.error ?? `Request failed with status ${res.status}`);
+    }
+    return data;
+  }
+  async list(opts = {}) {
+    const params = new URLSearchParams;
+    if (opts.compact)
+      params.set("compact", "true");
+    if (opts.fields)
+      params.set("fields", opts.fields);
+    const qs = params.toString() ? `?${params.toString()}` : "";
+    return this.request(`/api/connectors${qs}`);
+  }
+  async get(name) {
+    return this.request(`/api/connectors/${encodeURIComponent(normalizeConnectorSlug(name))}`);
+  }
+  async listOperations(name) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/operations`);
+  }
+  async getOperationHelp(name, command) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/operations/${encodeURIComponent(command)}`);
+  }
+  async getManifest(options = {}) {
+    const params = new URLSearchParams;
+    if (options.includeOperations)
+      params.set("includeOperations", "true");
+    if (options.connectorNames?.length)
+      params.set("connectors", options.connectorNames.map(normalizeConnectorSlug).join(","));
+    const qs = params.toString() ? `?${params.toString()}` : "";
+    return this.request(`/api/connectors/manifest${qs}`);
+  }
+  async runOperation(name, args, options = {}) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/operations/run`, {
+      method: "POST",
+      body: JSON.stringify({
+        args,
+        ...options.format ? { format: options.format } : {},
+        ...options.timeout !== undefined ? { timeout: options.timeout } : {}
+      })
+    });
+  }
+  async runStructuredOperation(name, options) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/operations/run`, {
+      method: "POST",
+      body: JSON.stringify({
+        operation: options.operation,
+        ...options.input ? { input: options.input } : {},
+        ...options.profile ? { profile: options.profile } : {},
+        ...options.timeout !== undefined ? { timeout: options.timeout } : {},
+        ...options.parseJson !== undefined ? { parseJson: options.parseJson } : {}
+      })
+    });
+  }
+  async install(name) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/install`, {
+      method: "POST"
+    });
+  }
+  async uninstall(name) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/uninstall`, {
+      method: "POST"
+    });
+  }
+  async setKey(name, key, field) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/key`, {
+      method: "POST",
+      body: JSON.stringify({ key, ...field ? { field } : {} })
+    });
+  }
+  async refresh(name) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/refresh`, {
+      method: "POST"
+    });
+  }
+  async getProfiles(name) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/profiles`);
+  }
+  async switchProfile(name, profileId) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/profiles/switch`, {
+      method: "POST",
+      body: JSON.stringify({ profile: profileId })
+    });
+  }
+  async deleteProfile(name, profileId) {
+    name = normalizeConnectorSlug(name);
+    return this.request(`/api/connectors/${encodeURIComponent(name)}/profiles/${encodeURIComponent(profileId)}`, { method: "DELETE" });
+  }
+  async getActivity(limit) {
+    const entries = await this.request("/api/activity");
+    return limit !== undefined ? entries.slice(0, limit) : entries;
+  }
+  async update() {
+    return this.request("/api/update", { method: "POST" });
+  }
+  async export() {
+    return this.request("/api/export");
+  }
+  async import(data) {
+    return this.request("/api/import", {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async run(name, args = [], options = {}) {
+    const { timeout = 30000, format, cwd } = options;
+    const bin = `${this.connectorsDir}/connect-${name}`;
+    const fullArgs = format ? [...args, "--format", format] : [...args];
+    const { execFile } = await import("child_process");
+    const { promisify } = await import("util");
+    const execFileAsync = promisify(execFile);
+    try {
+      const { stdout, stderr } = await execFileAsync(bin, fullArgs, {
+        timeout,
+        cwd,
+        maxBuffer: 10485760,
+        env: { ...process.env }
+      });
+      const output = stdout || stderr;
+      return { success: true, output: output.trimEnd(), exitCode: 0 };
+    } catch (err) {
+      const exitCode = typeof err.code === "number" ? err.code : err.status ?? 1;
+      const output = (err.stdout || err.stderr || err.message || "").trimEnd();
+      return { success: false, output, exitCode };
+    }
+  }
+  async runJson(name, args = [], options = {}) {
+    const result = await this.run(name, args, { ...options, format: "json" });
+    if (!result.success) {
+      throw new Error(`Connector "${name}" exited with code ${result.exitCode}: ${result.output}`);
+    }
+    try {
+      return JSON.parse(result.output);
+    } catch {
+      throw new Error(`Failed to parse JSON output from connector "${name}": ${result.output}`);
+    }
+  }
+  async search(query, opts) {
+    const args = ["search", "query", query];
+    if (opts?.numResults !== undefined) {
+      args.push("--num-results", String(opts.numResults));
+    }
+    if (opts?.type) {
+      args.push("--type", opts.type);
+    }
+    return this.runJson("exa", args);
+  }
+}
+
+class ConnectorsClient extends LocalConnectorsClient {
+}
+
+class HostedConnectorsClient {
+  apiUrl;
+  apiKey;
+  fetchImpl;
+  headers;
+  constructor(options) {
+    if (!options.apiUrl.trim())
+      throw new Error("apiUrl is required");
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.headers = options.headers ?? {};
+  }
+  async whoami() {
+    return this.request("/auth/whoami");
+  }
+  async getContract() {
+    return this.request("/contract");
+  }
+  async listConnectors(options = {}) {
+    const query = new URLSearchParams;
+    if (options.search)
+      query.set("search", options.search);
+    return this.request(`/connectors${query.size ? `?${query.toString()}` : ""}`);
+  }
+  async getConnector(connectorSlug) {
+    connectorSlug = normalizeConnectorSlug(connectorSlug);
+    return this.request(`/connectors/${encodeURIComponent(connectorSlug)}`);
+  }
+  async getConnectorDocs(connectorSlug) {
+    connectorSlug = normalizeConnectorSlug(connectorSlug);
+    return this.request(`/connectors/${encodeURIComponent(connectorSlug)}/docs`);
+  }
+  async getConnectorOperations(connectorSlug) {
+    connectorSlug = normalizeConnectorSlug(connectorSlug);
+    return this.request(`/connectors/${encodeURIComponent(connectorSlug)}/operations`);
+  }
+  async getConnectorAuthUrl(connectorSlug, options = {}) {
+    connectorSlug = normalizeConnectorSlug(connectorSlug);
+    const query = new URLSearchParams;
+    if (options.redirectUrl)
+      query.set("redirectUrl", options.redirectUrl);
+    if (options.returnUrl)
+      query.set("returnUrl", options.returnUrl);
+    if (options.profileName)
+      query.set("profileName", options.profileName);
+    if (options.scopes?.length)
+      query.set("scopes", options.scopes.join(","));
+    return this.request(`/connectors/${encodeURIComponent(connectorSlug)}/auth-url${query.size ? `?${query.toString()}` : ""}`);
+  }
+  async listAccounts() {
+    return this.request("/accounts");
+  }
+  async getAccountConnectionStatus() {
+    return this.request("/accounts/status");
+  }
+  async connectAccount(input) {
+    return this.request("/accounts", {
+      method: "POST",
+      body: JSON.stringify({
+        ...input,
+        connectorSlug: normalizeConnectorSlug(input.connectorSlug)
+      })
+    });
+  }
+  async listAccountProfiles(accountId) {
+    return this.request(`/accounts/${encodeURIComponent(accountId)}/profiles`);
+  }
+  async revokeAccount(accountId) {
+    return this.request(`/accounts/${encodeURIComponent(accountId)}`, { method: "DELETE" });
+  }
+  async revokeAccountProfile(accountId, profileName) {
+    return this.request(`/accounts/${encodeURIComponent(accountId)}/profiles/${encodeURIComponent(profileName)}`, { method: "DELETE" });
+  }
+  async checkAccountCredentials(accountId, profileName) {
+    return this.request(`/accounts/${encodeURIComponent(accountId)}/profiles/${encodeURIComponent(profileName)}/credential-check`);
+  }
+  async listRuns() {
+    return this.request("/runs");
+  }
+  async submitRun(input) {
+    return this.request("/runs", {
+      method: "POST",
+      body: JSON.stringify({
+        ...input,
+        connectorSlug: normalizeConnectorSlug(input.connectorSlug)
+      })
+    });
+  }
+  async getRun(runId) {
+    return this.request(`/runs/${encodeURIComponent(runId)}`);
+  }
+  async getRunStatus(runId) {
+    return this.request(`/runs/${encodeURIComponent(runId)}/status`);
+  }
+  async listRunLogs(runId) {
+    return this.request(`/runs/${encodeURIComponent(runId)}/logs`);
+  }
+  async listRunArtifacts(runId) {
+    return this.request(`/runs/${encodeURIComponent(runId)}/artifacts`);
+  }
+  async listApprovals() {
+    return this.request("/approvals");
+  }
+  async requestApproval(input) {
+    return this.request("/approvals", {
+      method: "POST",
+      body: JSON.stringify(normalizeHostedApprovalInput(input))
+    });
+  }
+  async decideApproval(id, decision) {
+    return this.request(`/approvals/${encodeURIComponent(id)}/${decision}`, {
+      method: "POST"
+    });
+  }
+  async getBillingStatus() {
+    return this.request("/billing/status");
+  }
+  async createBillingCustomer(input) {
+    return this.request("/billing/customers", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async createCheckoutSession(input) {
+    return this.request("/billing/checkout", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async createBillingPortalSession(input) {
+    return this.request("/billing/portal", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async addBillingCredits(input) {
+    return this.request("/billing/credits", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async listBillingTransactions() {
+    return this.request("/billing/transactions");
+  }
+  async listBillingInvoices() {
+    return this.request("/billing/invoices");
+  }
+  async getUsage() {
+    return this.request("/usage");
+  }
+  async getQuotas() {
+    return this.request("/quotas");
+  }
+  async getPolicy() {
+    return this.request("/policy");
+  }
+  async updatePolicy(input) {
+    return this.request("/policy", {
+      method: "PUT",
+      body: JSON.stringify(normalizePolicyConnectorLists(input))
+    });
+  }
+  async emergencyRevokePolicy(input = {}) {
+    return this.request("/policy/emergency-revoke", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async emergencyRestorePolicy() {
+    return this.request("/policy/emergency-restore", {
+      method: "POST",
+      body: JSON.stringify({})
+    });
+  }
+  async listAuditTimeline() {
+    return this.request("/audit-timeline");
+  }
+  async listTenantMappings() {
+    return this.request("/tenant-mappings");
+  }
+  async upsertTenantMapping(serviceSlug, externalOrganizationId, input = {}) {
+    return this.request(`/tenant-mappings/${encodeURIComponent(serviceSlug)}/${encodeURIComponent(externalOrganizationId)}`, {
+      method: "PUT",
+      body: JSON.stringify(input)
+    });
+  }
+  async request(path, init = {}) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.headers,
+      ...init.headers
+    };
+    if (this.apiKey)
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    const response = await this.fetchImpl(`${this.apiUrl}/api/v1${path}`, {
+      ...init,
+      headers
+    });
+    const payload = await readResponsePayload(response);
+    if (!response.ok) {
+      const errorPayload = isRecord(payload) ? payload : {};
+      throw new HostedConnectorsError(typeof errorPayload.error === "string" ? errorPayload.error : `request failed with status ${response.status}`, {
+        status: response.status,
+        code: typeof errorPayload.code === "string" ? errorPayload.code : undefined,
+        payload,
+        requestId: response.headers.get("x-request-id") ?? undefined
+      });
+    }
+    return payload;
+  }
+}
+function normalizeHostedApprovalInput(input) {
+  const requestPayload = input.requestPayload && typeof input.requestPayload.connectorSlug === "string" ? {
+    ...input.requestPayload,
+    connectorSlug: normalizeConnectorSlug(input.requestPayload.connectorSlug)
+  } : input.requestPayload;
+  return {
+    ...input,
+    resourceId: input.resourceId ? normalizeOperationKey(input.resourceId) : undefined,
+    requestPayload
+  };
+}
+async function readResponsePayload(response) {
+  const text = await response.text();
+  if (!text)
+    return;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var sdk_default = ConnectorsClient;
+export {
+  resolveLocalServeToken,
+  normalizeConnectorSlug,
+  sdk_default as default,
+  LocalConnectorsClient,
+  LOCAL_SERVE_TOKEN_HEADER,
+  LOCAL_SERVE_TOKEN_ENV,
+  HostedConnectorsError,
+  HostedConnectorsClient,
+  ConnectorsClient
+};

package/dist/sdk/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/platform-contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/auth.d.ts

@@ -1,5 +1,5 @@
 /**
- * Auth status detection and token management for the dashboard server.
+ * Auth status detection and token management for the local auth server.
  * Reads connector CLAUDE.md files to determine auth type, checks profile
  * directories for stored credentials, and handles token operations.
  */

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * Standalone entry point for the connector auth dashboard server.
+ * Standalone entry point for the connector API + OAuth server.
  * Usage: connectors-serve [--port 9876]
  */
 export {};

package/dist/server/serve-auth.d.ts

@@ -0,0 +1,54 @@
+/** Environment variable that supplies the serve token (wins over the file). */
+export declare const SERVE_TOKEN_ENV = "HASNA_CONNECTORS_SERVE_TOKEN";
+/** File name of the generated token under the connectors home. */
+export declare const SERVE_TOKEN_FILE = "serve-token";
+/** Stable refusal code, first token of every 401 body. */
+export declare const SERVE_UNAUTHORIZED_CODE = "CONNECTORS_SERVE_UNAUTHORIZED";
+/** The address the server binds by default: loopback only. */
+export declare const SERVE_DEFAULT_HOSTNAME = "127.0.0.1";
+export type ServeTokenSource = "env" | "file" | "generated" | "explicit";
+export interface ResolvedServeToken {
+    token: string;
+    source: ServeTokenSource;
+    /** Absolute path of the token file when the file tier was used or written. */
+    path: string | null;
+}
+/** Absolute path of the token file for the given (or effective) connectors home. */
+export declare function serveTokenPath(home?: string): string;
+/**
+ * Read the token a CLIENT should present, without ever creating one:
+ * the environment first, then the token file. `null` when neither exists.
+ */
+export declare function readServeToken(env?: Record<string, string | undefined>, home?: string): ResolvedServeToken | null;
+/**
+ * Resolve the token the SERVER enforces. An explicit token wins, then the
+ * environment, then the token file; when none exists a fresh 256-bit token
+ * is generated and written owner-only so same-user clients can find it.
+ */
+export declare function resolveServeToken(options?: {
+    token?: string;
+    env?: Record<string, string | undefined>;
+    home?: string;
+}): ResolvedServeToken;
+/** Extract the presented token from a request, or `null`. */
+export declare function presentedToken(req: Request): string | null;
+/** Constant-time comparison of a presented token with the enforced one. */
+export declare function tokenMatches(presented: string | null, expected: string): boolean;
+/**
+ * Does this route require the bearer token?
+ *
+ * Public: `/health` (liveness), the OAuth browser routes (vendor redirects
+ * cannot carry our header; they return no credential) and CORS preflights.
+ * Everything else the server answers — every `/api/*` route and `/mcp` — is
+ * gated.
+ */
+export declare function requiresServeAuth(pathname: string, method: string): boolean;
+/** True when the request may proceed. */
+export declare function isServeAuthorized(req: Request, token: string): boolean;
+/** The 401 body every gated route returns. Names the sources, never a value. */
+export declare function unauthorizedPayload(): {
+    error: string;
+    hint: string;
+};
+/** Human line for startup output. Never includes the token. */
+export declare function describeServeTokenSource(resolved: ResolvedServeToken): string;

package/dist/server/serve-auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/serve.d.ts

@@ -1,13 +1,25 @@
 /**
- * Reusable server starter for the connector auth dashboard.
+ * Reusable local API + OAuth server for connector auth.
  * Used by both the CLI `serve` command and the standalone `connectors-serve` binary.
- * Serves the Vite-built React/shadcn dashboard from dashboard/dist/.
  */
 export interface ServeOptions {
     port: number;
-    open?: boolean;
 }
-export declare function startServer(requestedPort: number, options?: {
-    open?: boolean;
+export interface StartServerOptions {
+    /** Refuse to start when `requestedPort` is taken (OAuth needs a fixed port). */
     strict?: boolean;
-}): Promise<number>;
+    /**
+     * Interface to bind. Defaults to loopback (`127.0.0.1`): this server hands
+     * out vendor credentials on `/api/export` and must never listen on every
+     * interface by accident. An operator who really needs another address must
+     * name it.
+     */
+    hostname?: string;
+    /**
+     * The bearer token every `/api/*` and `/mcp` request must present. When
+     * omitted the token is `HASNA_CONNECTORS_SERVE_TOKEN`, then the owner-only
+     * `<connectors home>/serve-token` file, generated on first start.
+     */
+    token?: string;
+}
+export declare function startServer(requestedPort: number, options?: StartServerOptions): Promise<number>;

package/dist/server/server-auth-gate.test.d.ts

@@ -0,0 +1 @@
+export {};