@hasna/connectors 1.4.5 → 1.4.7

package/dist/sdk/index.d.ts

@@ -0,0 +1,696 @@
+export interface AuthStatus {
+    type: "apikey" | "api_key" | "oauth" | "bearer" | "none";
+    configured?: boolean;
+    connected?: boolean;
+    expiresAt?: number | null;
+    tokenExpiry?: number | null;
+    hasRefreshToken?: boolean;
+    profile?: string;
+    envVars?: Array<{
+        variable: string;
+        description: string;
+        set: boolean;
+    }>;
+    envVarSetCount?: number;
+    envVarTotalCount?: number;
+}
+export interface ConnectorSummary {
+    name: string;
+    category: string;
+    installed: boolean;
+}
+export interface Connector {
+    name: string;
+    displayName: string;
+    description: string;
+    category: string;
+    version?: string;
+    installed: boolean;
+    auth: AuthStatus | null;
+    overview?: string | null;
+}
+export interface ConnectorOperationsResponse {
+    connector: string;
+    displayName: string;
+    auth?: AuthStatus;
+    commands: string[];
+    operations: ConnectorOperationDescriptor[];
+    helpText: string;
+}
+export interface ConnectorOperationDescriptor {
+    name: string;
+    aliases: string[];
+    usage: string;
+    summary: string;
+    source: "internal" | "cli";
+}
+export interface ConnectorOperationHelpResponse {
+    connector: string;
+    displayName: string;
+    command: string;
+    help: string;
+}
+export interface ConnectorCapabilityRuntime {
+    packageName: "@hasna/connectors";
+    connectorId: string;
+    legacyConnectorId: string;
+    packagePath: string;
+    configDirName: string;
+    legacyConfigDirName: string;
+    internal: boolean;
+    packageDirectory: boolean;
+    commandSurface: boolean;
+}
+export interface ConnectorCapabilityAuth {
+    type: AuthStatus["type"];
+    summary: string | null;
+    envVars: Array<{
+        variable: string;
+        description: string;
+    }>;
+}
+export interface ConnectorCapabilityDocs {
+    overview: string;
+    cliCommands: string;
+    dataStorage: string | null;
+}
+export interface ConnectorCapability {
+    id: string;
+    name: string;
+    displayName: string;
+    description: string;
+    category: string;
+    tags: string[];
+    version?: string;
+    aliases: string[];
+    runtime: ConnectorCapabilityRuntime;
+    auth: ConnectorCapabilityAuth;
+    docs: ConnectorCapabilityDocs;
+    operations?: ConnectorOperationDescriptor[];
+}
+export interface ConnectorCapabilityManifest {
+    version: 1;
+    packageName: "@hasna/connectors";
+    packageVersion: string;
+    generatedAt: string;
+    categories: readonly string[];
+    connectorCount: number;
+    connectors: ConnectorCapability[];
+}
+export interface RunOperationResponse {
+    connector: string;
+    displayName: string;
+    success: boolean;
+    output: string;
+}
+export interface StructuredRunOperationOptions<TInput extends Record<string, unknown> = Record<string, unknown>> {
+    operation: string;
+    input?: TInput;
+    profile?: string;
+    timeout?: number;
+    parseJson?: boolean;
+}
+export interface StructuredRunOperationResponse<TData = unknown> {
+    connector: string;
+    displayName: string;
+    operation: string;
+    profile?: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    success: boolean;
+    data?: TData;
+}
+export interface Profile {
+    id: string;
+    [key: string]: unknown;
+}
+export interface ProfilesResponse {
+    current: string;
+    profiles: Profile[];
+}
+export interface ActivityEntry {
+    action: string;
+    connector: string;
+    timestamp: number;
+    detail?: string;
+}
+export interface UpdateResult {
+    name: string;
+    success: boolean;
+    error?: string;
+}
+export interface UpdateResponse {
+    results: UpdateResult[];
+    count: number;
+    total: number;
+}
+export interface InstallResponse {
+    success: boolean;
+    name: string;
+}
+export interface UninstallResponse {
+    success: boolean;
+    name: string;
+}
+export interface SetKeyResponse {
+    success: boolean;
+}
+export interface RefreshResponse {
+    success: boolean;
+    expiresAt?: number | null;
+    error?: string;
+}
+export interface SwitchProfileResponse {
+    success: boolean;
+    profile: string;
+}
+export interface ApiError {
+    error: string;
+}
+export interface RunResult {
+    success: boolean;
+    output: string;
+    exitCode: number;
+}
+export interface RunOptions {
+    /** Timeout in milliseconds. Default: 30000 */
+    timeout?: number;
+    /** Output format passed to the connector CLI (e.g. "json") */
+    format?: string;
+    /** Working directory for the connector process */
+    cwd?: string;
+}
+export interface ConnectorsClientOptions {
+    /** Base URL of the connectors server. Defaults to http://localhost:9876 */
+    serverUrl?: string;
+    /** Directory where connector binaries are installed. Default: .connectors */
+    connectorsDir?: string;
+    /**
+     * Bearer token `connectors-serve` requires on every `/api/*` request.
+     * When omitted the client reads `HASNA_CONNECTORS_SERVE_TOKEN`, then the
+     * owner-only `<connectors home>/serve-token` file the server writes on first
+     * start — the same two sources the server enforces — so a same-user process
+     * needs no configuration. A client with no token gets a 401 from the server,
+     * never silent anonymous access.
+     */
+    token?: string;
+    /**
+     * Environment used to locate the token (`HASNA_CONNECTORS_SERVE_TOKEN`,
+     * `HASNA_CONNECTORS_DIR`, `HOME`). Defaults to `process.env`.
+     */
+    env?: Record<string, string | undefined>;
+}
+/** Environment variable that supplies the local serve token (mirrors the server). */
+export declare const LOCAL_SERVE_TOKEN_ENV = "HASNA_CONNECTORS_SERVE_TOKEN";
+/** Header the client sends alongside `Authorization: Bearer`. */
+export declare const LOCAL_SERVE_TOKEN_HEADER = "X-Connectors-Token";
+/**
+ * Locate the local serve token WITHOUT creating one: the environment first,
+ * then `<connectors home>/serve-token`, where the home is
+ * `HASNA_CONNECTORS_DIR` when set, otherwise `~/.hasna/connectors`.
+ *
+ * Reads only node builtins so the SDK bundle stays self-contained; returns
+ * `null` when nothing is configured (the server then answers 401).
+ */
+export declare function resolveLocalServeToken(env?: Record<string, string | undefined>): string | null;
+export interface ListOptions {
+    /** Return compact list (name, category, installed only) */
+    compact?: boolean;
+    /** Comma-separated list of fields to return */
+    fields?: string;
+}
+export interface RunOperationOptions {
+    format?: "json" | "pretty";
+    timeout?: number;
+}
+export interface ManifestOptions {
+    includeOperations?: boolean;
+    connectorNames?: string[];
+}
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface HostedConnectorsClientOptions {
+    /** Base URL of the hosted platform-connectors API, for example https://connectors.example */
+    apiUrl: string;
+    /** Bearer API key issued by the hosted platform. */
+    apiKey?: string;
+    /** Fetch implementation for tests, browsers, or custom runtimes. Defaults to global fetch. */
+    fetchImpl?: FetchLike;
+    /** Additional headers to send with every hosted API request. */
+    headers?: Record<string, string>;
+}
+export interface HostedWhoamiResponse {
+    organizationId: string;
+    userId: string;
+    authMethod: "api_key" | "session" | string;
+    scopes: string[];
+    serviceConsumer?: {
+        serviceSlug: string;
+        externalOrganizationId: string;
+        externalOrganizationSlug?: string | null;
+    } | null;
+}
+export interface HostedApiContract {
+    service: string;
+    version: string;
+    basePath: "/api/v1" | string;
+    auth: Record<string, unknown>;
+    endpoints: Array<{
+        method: string;
+        path: string;
+        scopes: string[];
+        description: string;
+    }>;
+    errors: Array<{
+        code: string;
+        status: number;
+        retryable: boolean;
+    }>;
+}
+export interface HostedConnectorSummary {
+    name: string;
+    displayName: string;
+    description: string;
+    category: string;
+    version?: string | null;
+    tags: string[];
+    hasCommandSurface: boolean;
+}
+export interface HostedConnectorAuthUrl {
+    connector: string;
+    provider: string | null;
+    available: boolean;
+    url: string | null;
+    redirectUrl: string;
+    scopes?: string[];
+    state?: string;
+    reason?: string;
+}
+export interface HostedAuthUrlOptions {
+    redirectUrl?: string;
+    returnUrl?: string;
+    profileName?: string;
+    scopes?: string[];
+}
+export interface HostedAccountConnectionStatus {
+    connectorSlug: string;
+    connected: boolean;
+    accountCount: number;
+    profileCount: number;
+    statuses: string[];
+}
+export interface HostedAccount {
+    id: string;
+    organizationId?: string;
+    connectorSlug: string;
+    displayName: string;
+    authType: string;
+    externalAccountId?: string | null;
+    status?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface HostedProfile {
+    id?: string;
+    accountId?: string;
+    profileName: string;
+    oauthScopes?: string[];
+    expiresAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface HostedConnectAccountInput {
+    connectorSlug: string;
+    displayName?: string;
+    authType?: string;
+    externalAccountId?: string;
+    profileName?: string;
+    credentials: Record<string, unknown>;
+    oauthScopes?: string[];
+    expiresAt?: string;
+}
+export interface HostedConnectAccountResponse {
+    account: HostedAccount;
+    profile: HostedProfile;
+}
+export interface HostedCredentialCheck {
+    available: boolean;
+}
+export type HostedRunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "canceled" | string;
+export interface HostedRun {
+    id: string;
+    connector: string;
+    connectorSlug?: string;
+    operationName: string;
+    status: HostedRunStatus;
+    accountId?: string | null;
+    profileName?: string | null;
+    idempotencyKey?: string | null;
+    requestSource?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface HostedRunPollingStatus extends HostedRun {
+    terminal: boolean;
+    recommendedPollAfterMs: number | null;
+}
+export interface HostedSubmitRunInput {
+    connectorSlug: string;
+    operationName: string;
+    args?: string[];
+    input?: Record<string, unknown>;
+    accountId?: string;
+    profileName?: string;
+    requestedByAgentId?: string;
+    idempotencyKey?: string;
+    estimatedCredits?: number;
+}
+export interface HostedApprovalRequiredRun {
+    status: "approval_required";
+    approval: HostedApproval;
+}
+export interface HostedRunLog {
+    id?: string;
+    runId?: string;
+    sequence?: number;
+    level?: string;
+    message?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export interface HostedRunArtifact {
+    id?: string;
+    runId?: string;
+    fileName?: string;
+    storageProvider?: string;
+    storageBucket?: string | null;
+    storageKey?: string | null;
+    sourceUri?: string | null;
+    name?: string;
+    contentType?: string;
+    sizeBytes?: number;
+    byteSize?: number | null;
+    sha256?: string;
+    url?: string;
+    [key: string]: unknown;
+}
+export interface HostedApproval {
+    id: string;
+    status: "pending" | "approved" | "rejected" | "expired" | string;
+    actionType: string;
+    resourceType: string;
+    resourceId?: string | null;
+    reason?: string | null;
+    requestPayload?: Record<string, unknown>;
+    createdAt?: string;
+    expiresAt?: string | null;
+    [key: string]: unknown;
+}
+export interface HostedRequestApprovalInput {
+    actionType: string;
+    resourceType: string;
+    resourceId?: string;
+    reason?: string;
+    requestPayload?: Record<string, unknown>;
+    requestedByAgentId?: string;
+    expiresAt?: string;
+}
+export interface HostedBillingStatus {
+    customer?: Record<string, unknown> | null;
+    subscription?: Record<string, unknown> | null;
+    creditBalance?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface HostedBillingCustomerInput {
+    email?: string;
+    currency?: string;
+    providerCustomerId?: string;
+}
+export interface HostedCheckoutSessionInput {
+    priceId: string;
+    successUrl: string;
+    cancelUrl: string;
+    creditPackCredits?: number;
+    idempotencyKey: string;
+}
+export interface HostedPortalSessionInput {
+    returnUrl: string;
+    idempotencyKey: string;
+}
+export interface HostedAddCreditsInput {
+    amountCredits: number;
+    idempotencyKey: string;
+    description?: string;
+}
+export interface HostedUsage {
+    runs: number;
+    creditsUsed?: number;
+    creditBalance?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface HostedQuotas {
+    maxRunsPerMinute: number | null;
+    spendingLimitCredits: number | null;
+    creditsUsed: number;
+    creditBalance?: Record<string, unknown>;
+}
+export interface HostedPolicy {
+    connectorAllowlist?: string[];
+    connectorBlocklist?: string[];
+    operationAllowlist?: string[];
+    operationDenylist?: string[];
+    approvalRequiredOperations?: string[];
+    [key: string]: unknown;
+}
+export interface HostedAuditTimelineEvent {
+    id: string;
+    action: string;
+    resourceType: string;
+    resourceId?: string | null;
+    outcome: string;
+    code: string;
+    message: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export interface HostedTenantMapping {
+    organizationId: string;
+    serviceSlug: string;
+    externalOrganizationId: string;
+    externalOrganizationSlug?: string | null;
+    displayName?: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface HostedTenantMappingInput {
+    externalOrganizationSlug?: string;
+    displayName?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface HostedApiErrorPayload {
+    error?: string;
+    code?: string;
+    [key: string]: unknown;
+}
+export declare class HostedConnectorsError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly payload: unknown;
+    readonly requestId?: string;
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        payload: unknown;
+        requestId?: string;
+    });
+}
+export declare function normalizeConnectorSlug(slug: string): string;
+export declare class LocalConnectorsClient {
+    private readonly baseUrl;
+    private readonly connectorsDir;
+    private readonly token;
+    constructor(options?: ConnectorsClientOptions);
+    /** True when a serve token was supplied or located; false means the server will answer 401. */
+    get hasToken(): boolean;
+    private request;
+    /**
+     * List all connectors.
+     * @param opts.compact - Return compact list (name, category, installed only)
+     * @param opts.fields - Comma-separated list of fields to return
+     */
+    list(opts: ListOptions & {
+        compact: true;
+    }): Promise<ConnectorSummary[]>;
+    list(opts?: ListOptions): Promise<Connector[]>;
+    /**
+     * Get a single connector by name.
+     */
+    get(name: string): Promise<Connector>;
+    /**
+     * List runnable operations for a connector.
+     */
+    listOperations(name: string): Promise<ConnectorOperationsResponse>;
+    /**
+     * Get help text for a connector command.
+     */
+    getOperationHelp(name: string, command: string): Promise<ConnectorOperationHelpResponse>;
+    /**
+     * Get the platform-consumable connector capability manifest.
+     */
+    getManifest(options?: ManifestOptions): Promise<ConnectorCapabilityManifest>;
+    /**
+     * Execute a connector command.
+     */
+    runOperation(name: string, args: string[], options?: RunOperationOptions): Promise<RunOperationResponse>;
+    /**
+     * Execute a structured connector operation.
+     */
+    runStructuredOperation<TData = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(name: string, options: StructuredRunOperationOptions<TInput>): Promise<StructuredRunOperationResponse<TData>>;
+    /**
+     * Install a connector.
+     */
+    install(name: string): Promise<InstallResponse>;
+    /**
+     * Uninstall a connector.
+     */
+    uninstall(name: string): Promise<UninstallResponse>;
+    /**
+     * Save an API key for a connector.
+     * @param name - Connector name
+     * @param key - The API key value
+     * @param field - Optional field name (for connectors with multiple key fields)
+     */
+    setKey(name: string, key: string, field?: string): Promise<SetKeyResponse>;
+    /**
+     * Refresh OAuth tokens for a connector.
+     */
+    refresh(name: string): Promise<RefreshResponse>;
+    /**
+     * Get profiles for a connector.
+     */
+    getProfiles(name: string): Promise<ProfilesResponse>;
+    /**
+     * Switch the active profile for a connector.
+     */
+    switchProfile(name: string, profileId: string): Promise<SwitchProfileResponse>;
+    /**
+     * Delete a profile for a connector. Cannot delete the "default" profile.
+     */
+    deleteProfile(name: string, profileId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get the activity log.
+     * @param limit - Maximum number of entries to return (client-side truncation)
+     */
+    getActivity(limit?: number): Promise<ActivityEntry[]>;
+    /**
+     * Re-install all installed connectors (update from package).
+     */
+    update(): Promise<UpdateResponse>;
+    /**
+     * Export all connector credentials.
+     */
+    export(): Promise<{
+        connectors: Record<string, unknown>;
+        exportedAt: string;
+    }>;
+    /**
+     * Import connector credentials from backup JSON.
+     */
+    import(data: {
+        connectors: Record<string, {
+            profiles: Record<string, unknown>;
+        }>;
+    }): Promise<{
+        success: boolean;
+        imported: number;
+    }>;
+    /**
+     * Run a connector CLI binary and capture its output.
+     * @param name - Connector name (e.g. "exa"). Binary is resolved as `{connectorsDir}/connect-{name}`.
+     * @param args - Arguments to pass to the connector CLI.
+     * @param options - Execution options (timeout, format, cwd).
+     */
+    run(name: string, args?: string[], options?: RunOptions): Promise<RunResult>;
+    /**
+     * Run a connector CLI binary and parse the output as JSON.
+     * @param name - Connector name.
+     * @param args - Arguments to pass to the connector CLI.
+     * @param options - Execution options (timeout, cwd). Format is forced to "json".
+     */
+    runJson<T = unknown>(name: string, args?: string[], options?: Omit<RunOptions, "format">): Promise<T>;
+    /**
+     * Convenience method for Exa search.
+     * @param query - Search query string.
+     * @param opts - Search options.
+     */
+    search(query: string, opts?: {
+        numResults?: number;
+        type?: string;
+    }): Promise<any>;
+}
+export declare class ConnectorsClient extends LocalConnectorsClient {
+}
+export declare class HostedConnectorsClient {
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly headers;
+    constructor(options: HostedConnectorsClientOptions);
+    whoami(): Promise<HostedWhoamiResponse>;
+    getContract(): Promise<HostedApiContract>;
+    listConnectors(options?: {
+        search?: string;
+    }): Promise<HostedConnectorSummary[]>;
+    getConnector(connectorSlug: string): Promise<HostedConnectorSummary & Record<string, unknown>>;
+    getConnectorDocs(connectorSlug: string): Promise<{
+        connector: string;
+        docs: ConnectorCapabilityDocs;
+    }>;
+    getConnectorOperations(connectorSlug: string): Promise<ConnectorOperationsResponse>;
+    getConnectorAuthUrl(connectorSlug: string, options?: HostedAuthUrlOptions): Promise<HostedConnectorAuthUrl>;
+    listAccounts(): Promise<HostedAccount[]>;
+    getAccountConnectionStatus(): Promise<HostedAccountConnectionStatus[]>;
+    connectAccount(input: HostedConnectAccountInput): Promise<HostedConnectAccountResponse>;
+    listAccountProfiles(accountId: string): Promise<HostedProfile[]>;
+    revokeAccount(accountId: string): Promise<{
+        account: HostedAccount;
+        profilesRevoked: number;
+    }>;
+    revokeAccountProfile(accountId: string, profileName: string): Promise<HostedProfile>;
+    checkAccountCredentials(accountId: string, profileName: string): Promise<HostedCredentialCheck>;
+    listRuns(): Promise<HostedRun[]>;
+    submitRun(input: HostedSubmitRunInput): Promise<HostedRun | HostedApprovalRequiredRun>;
+    getRun(runId: string): Promise<HostedRun>;
+    getRunStatus(runId: string): Promise<HostedRunPollingStatus>;
+    listRunLogs(runId: string): Promise<HostedRunLog[]>;
+    listRunArtifacts(runId: string): Promise<HostedRunArtifact[]>;
+    listApprovals(): Promise<HostedApproval[]>;
+    requestApproval(input: HostedRequestApprovalInput): Promise<HostedApproval>;
+    decideApproval(id: string, decision: "approve" | "reject"): Promise<HostedApproval>;
+    getBillingStatus(): Promise<HostedBillingStatus>;
+    createBillingCustomer(input: HostedBillingCustomerInput): Promise<Record<string, unknown>>;
+    createCheckoutSession(input: HostedCheckoutSessionInput): Promise<Record<string, unknown>>;
+    createBillingPortalSession(input: HostedPortalSessionInput): Promise<Record<string, unknown>>;
+    addBillingCredits(input: HostedAddCreditsInput): Promise<Record<string, unknown>>;
+    listBillingTransactions(): Promise<Array<Record<string, unknown>>>;
+    listBillingInvoices(): Promise<Array<Record<string, unknown>>>;
+    getUsage(): Promise<HostedUsage>;
+    getQuotas(): Promise<HostedQuotas>;
+    getPolicy(): Promise<HostedPolicy>;
+    updatePolicy(input: HostedPolicy): Promise<HostedPolicy>;
+    emergencyRevokePolicy(input?: {
+        reason?: string;
+    }): Promise<HostedPolicy>;
+    emergencyRestorePolicy(): Promise<HostedPolicy>;
+    listAuditTimeline(): Promise<HostedAuditTimelineEvent[]>;
+    listTenantMappings(): Promise<HostedTenantMapping[]>;
+    upsertTenantMapping(serviceSlug: string, externalOrganizationId: string, input?: HostedTenantMappingInput): Promise<HostedTenantMapping>;
+    private request;
+}
+export default ConnectorsClient;