@opengeni/api-router 0.23.1 → 0.30.0

package/dist/integrations/api-integrations.d.ts

@@ -0,0 +1,24 @@
+import { type IntegrationCredentialResolver, type IntegrationInvocationAuthority, type IntegrationTransport } from "@opengeni/capabilities";
+import { ApiIntegrationPreview, type IntegrationSource } from "@opengeni/contracts";
+import type { StoredApiIntegrationRevision } from "@opengeni/db";
+export type ApiIntegrationConnectionDescriptor = {
+    id: string;
+    kind: "oauth2" | "api_key" | "app_install" | "delegated";
+    providerDomain: string;
+    scopes: string[];
+    ownership: "workspace" | "personal";
+};
+export type ResolvedApiIntegrationPreview = {
+    preview: ApiIntegrationPreview;
+    revision: StoredApiIntegrationRevision;
+    provider: string | null;
+    requiredScopes: string[];
+    authScheme: Record<string, unknown>;
+};
+export declare function resolveApiIntegrationPreview(input: {
+    source: IntegrationSource;
+    connection: ApiIntegrationConnectionDescriptor | null;
+    transport: IntegrationTransport;
+    credentialResolver?: IntegrationCredentialResolver;
+    authority: IntegrationInvocationAuthority;
+}): Promise<ResolvedApiIntegrationPreview>;

package/dist/integrations/atlassian.d.ts

@@ -0,0 +1,176 @@
+import type { AccessGrant, ScheduledTask } from "@opengeni/contracts";
+import { AtlassianOAuthStartResponse, type AtlassianDisconnectRequest, type AtlassianLifecycleActionRequest, type AtlassianOAuthStartRequest } from "@opengeni/contracts/atlassian";
+import { type ApiRouteDeps } from "@opengeni/core";
+import { getConnectionMetadata } from "@opengeni/db";
+type AtlassianConnectionRecord = NonNullable<Awaited<ReturnType<typeof getConnectionMetadata>>>;
+export declare function startAtlassianOAuth(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    requestUrl: string;
+    payload: AtlassianOAuthStartRequest;
+}): Promise<AtlassianOAuthStartResponse>;
+export declare function completeAtlassianOAuthCallback(deps: ApiRouteDeps, input: {
+    code?: string | undefined;
+    state?: string | undefined;
+    error?: string | undefined;
+    requestUrl: string;
+}): Promise<{
+    redirectTo: string;
+}>;
+export declare function browseAtlassianSources(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+}): Promise<{
+    connection: {
+        id: string;
+        accountId: string;
+        workspaceId: string;
+        subjectId: string | null;
+        providerDomain: string;
+        kind: "api_key" | "app_install" | "delegated" | "oauth2";
+        status: "active" | "error" | "needs_reauth" | "revoked";
+        grantedScopes: string[];
+        expiresAt: string | null;
+        lastRefreshAt: string | null;
+        lastUsedAt: string | null;
+        lastError: string | null;
+        version: number;
+        verifiedInstallAt?: string | null | undefined;
+        verifiedInstallVersion?: number | null | undefined;
+        metadata: Record<string, unknown>;
+        createdBySubjectId: string | null;
+        updatedBySubjectId: string | null;
+        createdAt: string;
+        updatedAt: string;
+    };
+    items: {
+        id: string;
+        cloudId: string;
+        siteName: string;
+        siteUrl: string;
+        resourceId: string;
+        key: string;
+        name: string;
+        kind: "confluence_space" | "jira_project";
+        description: string | null;
+        webUrl: string;
+    }[];
+}>;
+export declare function searchAtlassianLive(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    query: string;
+    product?: "jira" | "confluence" | undefined;
+    limit: number;
+}): Promise<({
+    kind: "jira_issue";
+    id: string;
+    key: string;
+    title: string;
+    sourceId: string | null;
+    sourceName: string | null;
+    status: string | null;
+    updatedAt: string | null;
+    url: string;
+} | {
+    kind: "confluence_page";
+    id: string;
+    key: null;
+    title: string;
+    sourceId: string | null;
+    sourceName: string | null;
+    status: null;
+    updatedAt: string | null;
+    url: string;
+})[]>;
+export declare function getAtlassianLiveItem(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    kind: "jira_issue" | "confluence_page";
+    id: string;
+}): Promise<{
+    kind: "jira_issue";
+    id: string;
+    key: string;
+    title: string;
+    source: {
+        id: string;
+        name: string;
+        siteName: string;
+    };
+    status: string | null;
+    issueType: string | null;
+    priority: string | null;
+    assignee: string | null;
+    reporter: string | null;
+    labels: string[];
+    createdAt: string | null;
+    updatedAt: string | null;
+    description: string;
+    comments: {
+        author: string | null;
+        createdAt: string | null;
+        body: string;
+    }[];
+    url: string;
+    content?: never;
+} | {
+    key?: never;
+    issueType?: never;
+    priority?: never;
+    assignee?: never;
+    reporter?: never;
+    labels?: never;
+    description?: never;
+    kind: "confluence_page";
+    id: string;
+    title: string;
+    source: {
+        id: string;
+        name: string;
+        siteName: string;
+    };
+    status: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    content: string;
+    comments: {
+        createdAt: string | null;
+        content: string;
+    }[];
+    url: string;
+}>;
+export declare function saveAtlassianSources(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    grant: AccessGrant;
+    payload: unknown;
+    canManageOrganizationDestination: boolean;
+    canManageWorkspaceDestination: boolean;
+    canManagePersonalDestination: boolean;
+}): Promise<import("@opengeni/db").ConnectionMetadataWithVerification>;
+export declare function transitionAtlassianLifecycle(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    payload: AtlassianLifecycleActionRequest;
+}): Promise<import("@opengeni/db").ConnectionMetadataWithVerification>;
+export declare function disconnectAtlassian(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+    connection: AtlassianConnectionRecord;
+    payload: AtlassianDisconnectRequest;
+}): Promise<import("@opengeni/db").ConnectionMetadataWithVerification | null>;
+export declare function revokeAtlassianScheduleAuthorization(deps: ApiRouteDeps, input: {
+    task: ScheduledTask;
+    subjectId: string;
+}): Promise<void>;
+export declare function isSelectableConfluenceSpaceType(value: unknown): boolean;
+export declare function confluenceNextUrl(cloudId: string, next: string): URL;
+export {};

package/dist/integrations/fiken.d.ts

@@ -0,0 +1,233 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+import type { Settings } from "@opengeni/config";
+import { FikenOAuthStartResponse, type AccessGrant, type ConnectionMetadata, type FikenCompanySummary, type FikenConnectionMetadata, type FikenOAuthStartRequest } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+import { type FetchLike } from "@opengeni/network";
+import { HTTPException } from "hono/http-exception";
+export type FikenOperation = "companies.list" | "contacts.list" | "contact.create" | "products.list" | "invoices.list" | "invoice.get" | "invoice_draft.create" | "bank_accounts.list" | "purchases.list" | "sales.list";
+export declare class FikenProviderError extends Error {
+    readonly code: string;
+    readonly status: number | null;
+    constructor(code: string, status?: number | null, providerMessage?: string | null);
+}
+export declare class FikenCredentialVerificationError extends HTTPException {
+    constructor(message: string);
+}
+export type FikenPage = {
+    page: number;
+    pageSize: number;
+    pageCount: number | null;
+    resultCount: number | null;
+};
+type FikenContext = {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string | null;
+    sessionId: string | null;
+};
+/**
+ * Validates a pasted Fiken personal API token before it enters encrypted
+ * storage, and discovers the companies it can act on. The companies list is
+ * the connection's bounded metadata; company slugs are re-validated by Fiken
+ * itself on every later call.
+ */
+export declare function verifyFikenApiToken(token: string, fetchImpl?: FetchLike): Promise<{
+    companies: FikenCompanySummary[];
+}>;
+export declare function fikenCredentialBundle(token: string): Record<string, unknown>;
+export declare function resolveFikenConnectionForTool(input: {
+    db: Database;
+    grant: AccessGrant;
+    sessionId: string | null;
+    requestedConnectionId?: string;
+}): Promise<{
+    connection: ConnectionMetadata;
+    metadata: FikenConnectionMetadata;
+    context: FikenContext;
+}>;
+export type FikenListInput = {
+    companySlug?: string | undefined;
+    page?: number | undefined;
+    pageSize?: number | undefined;
+};
+export declare class FikenClient {
+    private readonly db;
+    private readonly settings;
+    private readonly connection;
+    private readonly metadata;
+    private readonly context;
+    private readonly fetchImpl;
+    private readonly resolveCredential;
+    constructor(db: Database, settings: Settings, connection: ConnectionMetadata, metadata: FikenConnectionMetadata, context: FikenContext, fetchImpl?: FetchLike);
+    listCompanies(input?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        companies: Record<string, unknown>[];
+        page: FikenPage | null;
+    }>;
+    listContacts(input: FikenListInput & {
+        name?: string | undefined;
+        email?: string | undefined;
+        organizationNumber?: string | undefined;
+        customer?: boolean | undefined;
+        supplier?: boolean | undefined;
+        inactive?: boolean | undefined;
+    }): Promise<{
+        companySlug: string;
+        contacts: Record<string, unknown>[];
+        page: FikenPage | null;
+    }>;
+    createContact(input: {
+        companySlug?: string | undefined;
+        name: string;
+        email?: string | undefined;
+        organizationNumber?: string | undefined;
+        phoneNumber?: string | undefined;
+        customer?: boolean | undefined;
+        supplier?: boolean | undefined;
+    }): Promise<{
+        companySlug: string;
+        contactId: number;
+        receipt: {
+            credentialRole: "fiken_api_token";
+            credentialLabel: "Fiken API token";
+            connectionId: string;
+            operation: FikenOperation;
+            operationId?: string;
+        };
+    }>;
+    listProducts(input: FikenListInput & {
+        name?: string | undefined;
+        active?: boolean | undefined;
+    }): Promise<{
+        companySlug: string;
+        products: Record<string, unknown>[];
+        page: FikenPage | null;
+    }>;
+    listInvoices(input: FikenListInput & {
+        issueDateGe?: string | undefined;
+        issueDateLe?: string | undefined;
+        customerId?: number | undefined;
+        settled?: boolean | undefined;
+        invoiceNumber?: string | undefined;
+    }): Promise<{
+        companySlug: string;
+        invoices: Record<string, unknown>[];
+        page: FikenPage | null;
+    }>;
+    getInvoice(input: {
+        companySlug?: string | undefined;
+        invoiceId: number;
+    }): Promise<{
+        companySlug: string;
+        invoice: Record<string, unknown> | null;
+    }>;
+    createInvoiceDraft(input: {
+        companySlug?: string | undefined;
+        operationId: string;
+        customerId: number;
+        daysUntilDueDate: number;
+        invoiceText?: string | undefined;
+        yourReference?: string | undefined;
+        ourReference?: string | undefined;
+        currency?: string | undefined;
+        bankAccountNumber?: string | undefined;
+        lines: Array<{
+            description?: string | undefined;
+            productId?: number | undefined;
+            unitPriceCents?: number | undefined;
+            vatType?: string | undefined;
+            quantity: number;
+            discountPercent?: number | undefined;
+            incomeAccount?: string | undefined;
+            comment?: string | undefined;
+        }>;
+    }): Promise<{
+        companySlug: string;
+        draftId: number | null;
+        draft: Record<string, unknown>;
+        alreadyExisted: boolean;
+        receipt: {
+            credentialRole: "fiken_api_token";
+            credentialLabel: "Fiken API token";
+            connectionId: string;
+            operation: FikenOperation;
+            operationId?: string;
+        };
+    } | {
+        draft?: never;
+        companySlug: string;
+        draftId: number;
+        alreadyExisted: boolean;
+        receipt: {
+            credentialRole: "fiken_api_token";
+            credentialLabel: "Fiken API token";
+            connectionId: string;
+            operation: FikenOperation;
+            operationId?: string;
+        };
+    }>;
+    listBankAccounts(input: FikenListInput & {
+        inactive?: boolean | undefined;
+    }): Promise<{
+        companySlug: string;
+        bankAccounts: Record<string, unknown>[];
+        page: FikenPage | null;
+    }>;
+    listPurchases(input: FikenListInput & {
+        dateGe?: string | undefined;
+        dateLe?: string | undefined;
+        paid?: boolean | undefined;
+    }): Promise<{
+        companySlug: string;
+        purchases: Record<string, unknown>[];
+        page: FikenPage | null;
+    }>;
+    listSales(input: FikenListInput & {
+        dateGe?: string | undefined;
+        dateLe?: string | undefined;
+        settled?: boolean | undefined;
+    }): Promise<{
+        companySlug: string;
+        sales: Record<string, unknown>[];
+        page: FikenPage | null;
+    }>;
+    /**
+     * The company scope for a call: an explicit slug wins, then the connection's
+     * configured default, then the only verified company. Ambiguity is an error
+     * that lists the available slugs instead of guessing.
+     */
+    private companySlugFor;
+    private request;
+    private readResponse;
+    private markNeedsReauth;
+    private headersFor;
+    private receipt;
+    private recordAudit;
+}
+export declare function createFikenClient(deps: {
+    db: Database;
+    settings: Settings;
+    fikenFetch?: typeof fetch;
+}, resolved: Awaited<ReturnType<typeof resolveFikenConnectionForTool>>): FikenClient;
+export declare class FikenOAuthCallbackError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare function startFikenOAuth(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    requestUrl: string;
+    payload: FikenOAuthStartRequest;
+}): Promise<FikenOAuthStartResponse>;
+export declare function completeFikenOAuthCallback(deps: ApiRouteDeps, input: {
+    code?: string | undefined;
+    state?: string | undefined;
+    error?: string | undefined;
+    requestUrl: string;
+}): Promise<{
+    redirectTo: string;
+}>;
+export {};

package/dist/integrations/github-skill-source.d.ts

@@ -0,0 +1,5 @@
+import type { Settings } from "@opengeni/config";
+import type { GitHubSkillSourceClient } from "@opengeni/core";
+type GitHubJsonRequest = (path: string, maxBytes: number, label: string) => Promise<unknown>;
+export declare function createGitHubSkillSourceClient(settings: Settings, requestJson?: GitHubJsonRequest): GitHubSkillSourceClient;
+export {};

package/dist/integrations/google-drive.d.ts

@@ -1,6 +1,19 @@
+import type { AccessGrant, ScheduledTask } from "@opengeni/contracts";
 import { GoogleDriveOAuthStartResponse, type GoogleDriveDisconnectRequest, type GoogleDriveLifecycleActionRequest, type GoogleDriveOAuthStartRequest } from "@opengeni/contracts/google-drive";
+import { IntegrationFacetMutationResult } from "@opengeni/contracts";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { getConnectionMetadata } from "@opengeni/db";
+export declare function wakeGoogleDriveSourcesFromWorkspaceEvent(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    connectionId: string;
+    connectionOwnerSubjectId: string;
+    eventId: string;
+    driveId: string | null;
+}): Promise<{
+    enabled: boolean;
+    triggered: number;
+}>;
 type GoogleDriveConnectionRecord = NonNullable<Awaited<ReturnType<typeof getConnectionMetadata>>>;
 export declare function startGoogleDriveOAuth(deps: ApiRouteDeps, input: {
     accountId: string;
@@ -82,14 +95,86 @@ export declare function browseGoogleDrive(deps: ApiRouteDeps, input: {
     nextPageToken: string | null;
     incompleteSearch: boolean;
 }>;
+export declare function browseGoogleDriveFacetSource(deps: ApiRouteDeps, input: {
+    workspaceId: string;
+    subjectId: string;
+    capabilityId: string;
+    instanceKey: string;
+    facetKey: string;
+    parentId: string;
+    pageToken?: string | undefined;
+}): Promise<{
+    connection: {
+        id: string;
+        accountId: string;
+        workspaceId: string;
+        subjectId: string | null;
+        providerDomain: string;
+        kind: "api_key" | "app_install" | "delegated" | "oauth2";
+        status: "active" | "error" | "needs_reauth" | "revoked";
+        grantedScopes: string[];
+        expiresAt: string | null;
+        lastRefreshAt: string | null;
+        lastUsedAt: string | null;
+        lastError: string | null;
+        version: number;
+        verifiedInstallAt?: string | null | undefined;
+        verifiedInstallVersion?: number | null | undefined;
+        metadata: Record<string, unknown>;
+        createdBySubjectId: string | null;
+        updatedBySubjectId: string | null;
+        createdAt: string;
+        updatedAt: string;
+    };
+    parentId: string;
+    current: {
+        id: string;
+        name: string;
+        mimeType: string;
+        kind: "file" | "folder";
+        driveId: string | null;
+        modifiedTime: string | null;
+        size: string | null;
+        webViewLink: string | null;
+    } | null;
+    items: {
+        id: string;
+        name: string;
+        mimeType: string;
+        kind: "file" | "folder";
+        driveId: string | null;
+        modifiedTime: string | null;
+        size: string | null;
+        webViewLink: string | null;
+    }[];
+    nextPageToken: string | null;
+    incompleteSearch: boolean;
+}>;
+export declare function saveGoogleDriveFacetSource(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    capabilityId: string;
+    instanceKey: string;
+    facetKey: string;
+    payload: unknown;
+    canManageOrganizationDestination: boolean;
+    canManageWorkspaceDestination: boolean;
+    canManagePersonalDestination: boolean;
+}): Promise<IntegrationFacetMutationResult>;
 export declare function saveGoogleDriveSource(deps: ApiRouteDeps, input: {
     accountId: string;
     workspaceId: string;
     subjectId: string;
     connectionId: string;
+    grant: AccessGrant;
     payload: unknown;
     canManageOrganizationDestination: boolean;
     canManageWorkspaceDestination: boolean;
     canManagePersonalDestination: boolean;
 }): Promise<import("@opengeni/db").ConnectionMetadataWithVerification>;
+export declare function revokeKnowledgeSourceScheduleAuthorization(deps: ApiRouteDeps, input: {
+    task: ScheduledTask;
+    subjectId: string;
+}): Promise<void>;
 export {};

package/dist/integrations/oauth-client.d.ts

@@ -1,9 +1,11 @@
 import { type Settings } from "@opengeni/config";
-import { OAuthStartResponse, type OAuthStartRequest } from "@opengeni/contracts";
+import { OAuthStartResponse, type ConnectionOwnership, type OAuthStartRequest } from "@opengeni/contracts";
 import type { Observability } from "@opengeni/observability";
 import { type Database } from "@opengeni/db";
 export declare const oauthStateTtlMs: number;
 export declare const OFFICIAL_SLACK_MCP_URL: "https://mcp.slack.com/mcp";
+export declare const OFFICIAL_GMAIL_MCP_URL = "https://gmailmcp.googleapis.com/mcp/v1";
+export declare const OFFICIAL_GMAIL_MCP_SCOPES: readonly ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.compose", "https://www.googleapis.com/auth/gmail.modify"];
 export { OAUTH_MAX_RESPONSE_BYTES } from "@opengeni/network";
 type OAuthClientDeps = {
     db: Database;
@@ -37,6 +39,7 @@ export declare const OAUTH_START_DEADLINE_MS = 15000;
 export declare const OAUTH_CALLBACK_DEADLINE_MS = 30000;
 export type OAuthStartStage = "connection_lookup" | "mcp_challenge" | "protected_resource_metadata" | "authorization_server_metadata" | "client_registration";
 export declare function startMcpOAuth(deps: OAuthClientDeps, context: OAuthStartContext): Promise<OAuthStartResponse>;
+export declare function assertOfficialGmailPersonalOwnership(mcpUrl: string, ownership: ConnectionOwnership): void;
 export declare function completeMcpOAuthCallback(deps: OAuthClientDeps, input: {
     code?: string | undefined;
     state?: string | undefined;
@@ -45,6 +48,18 @@ export declare function completeMcpOAuthCallback(deps: OAuthClientDeps, input: {
 export declare function integrationBaseUrl(publicBaseUrl: string | undefined, requestUrl: string): string;
 export declare function requireIntegrationsStateSecret(settings: Settings): string;
 export declare function assertSlackAuthorizationServer(as: AuthorizationServerMetadata): void;
+export declare function assertGoogleAuthorizationServer(as: AuthorizationServerMetadata): void;
+export declare function buildAuthorizationUrl(input: {
+    endpoint: string;
+    settings: Settings;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    resource: string;
+    verifier: string;
+    scopes: string[];
+    resourceParameterSupported: boolean;
+}): string;
 export type OAuthPublicErrorFields = {
     errorClass: "OAuthOperationError";
     errorCode: "oauth_operation_failed";
@@ -53,3 +68,9 @@ export type OAuthPublicErrorFields = {
 };
 /** Allowlisted projection for public telemetry; canonical OAuth errors stay exact. */
 export declare function oauthPublicErrorFields(error: unknown): OAuthPublicErrorFields;
+export declare function chooseMcpAuthorizeScopes(input: {
+    mcpUrl: string;
+    requested: string[] | undefined;
+    challenged: string[] | undefined;
+    supported: string[];
+}): string[];

package/dist/integrations/provider-oauth.d.ts

@@ -0,0 +1,17 @@
+import { OAuthStartResponse, type ApiIntegrationOAuthStartRequest } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+export declare function startApiIntegrationProviderOAuth(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    requestUrl: string;
+    payload: ApiIntegrationOAuthStartRequest;
+}): Promise<OAuthStartResponse>;
+export declare function completeApiIntegrationProviderOAuth(deps: ApiRouteDeps, input: {
+    code?: string | undefined;
+    state?: string | undefined;
+    error?: string | undefined;
+    requestUrl: string;
+}): Promise<{
+    redirectTo: string;
+}>;