productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/sourceIngress.d.ts

@@ -0,0 +1,488 @@
+export type IngressPath = "mcp" | "nango" | "custom" | "browser";
+export type ApprovalState = "excluded" | "approved" | "revoked";
+export type SourceId = {
+    ingress_path: IngressPath;
+    provider: string;
+    connection_id: string;
+    external_id?: string;
+};
+export type EvidenceClass = "system_of_record" | "reference" | "communication" | "support_context" | "decision_context" | "context_only" | "approved_source_artifact";
+export type Sensitivity = "low" | "medium" | "high";
+export type Classification = {
+    source_category: string;
+    authority: "authoritative" | "supporting" | "context_only";
+    sensitivity: Sensitivity;
+    evidence_class: EvidenceClass;
+    model_exposure: "summary_only" | "full";
+    registered: boolean;
+};
+export declare const EVIDENCE_CLASS_GLOSS: Record<EvidenceClass, string>;
+export declare const SOURCE_CATEGORY_REGISTRY: Record<string, Omit<Classification, "registered">>;
+export declare const MOST_RESTRICTIVE_DEFAULT: Classification;
+export declare function classifyProvider(provider: string): Classification;
+export type NotionApprovedScope = {
+    page_ids?: string[];
+    database_ids?: string[];
+    window: {
+        from: string;
+        to: string;
+    };
+};
+export declare function parseNotionScope(raw: string): NotionApprovedScope;
+export declare function notionScopeValidationError(raw: string): string | null;
+export declare function notionScopeAllowsSelection(scope: string | undefined, selection: {
+    page_id?: string;
+    database_id?: string;
+}): boolean;
+export declare function sourceKey(id: Pick<SourceId, "provider" | "connection_id" | "external_id">): string;
+export type CompanyCanonicalSourceIdentity<Provider extends string = string> = {
+    foo_workspace: string;
+    provider: Provider;
+    canonical_connection_key: string;
+};
+export type GongCanonicalSourceIdentity = CompanyCanonicalSourceIdentity<"gong">;
+export type ZoomCanonicalSourceIdentity = CompanyCanonicalSourceIdentity<"zoom">;
+export declare function gongCanonicalSourceIdentity(input: {
+    foo_workspace: string;
+    canonical_connection_key: string;
+}): GongCanonicalSourceIdentity;
+export declare function gongWorkspaceSourceId(identity: GongCanonicalSourceIdentity): SourceId;
+export declare function zoomCanonicalSourceIdentity(input: {
+    foo_workspace: string;
+    canonical_connection_key: string;
+}): ZoomCanonicalSourceIdentity;
+export declare function zoomWorkspaceSourceId(identity: ZoomCanonicalSourceIdentity): SourceId;
+export type DiscoveryConnectionReady = {
+    event: "discovery_connection_ready";
+    connection_owner: "workspace" | "user";
+    admin_ref?: string;
+    connection_ref: string;
+};
+export declare function gongConnectionReady(input: {
+    connection_ref: string;
+    admin_ref: string;
+}): DiscoveryConnectionReady;
+export declare function zoomConnectionReady(input: {
+    connection_ref: string;
+    admin_ref: string;
+}): DiscoveryConnectionReady;
+export declare function firefliesConnectionReady(input: {
+    connection_ref: string;
+}): DiscoveryConnectionReady;
+export declare class MemberConnectionRefusal extends Error {
+    readonly action: "disconnect" | "rotate" | "revoke";
+    readonly actor_ref: string;
+    constructor(action: "disconnect" | "rotate" | "revoke", actor_ref: string, provider?: string);
+}
+export declare class PersonalCredentialRefused extends Error {
+    readonly handoff: string;
+    constructor(provider?: string);
+}
+export type CompanyConnectionGrant = {
+    grant_ref: string;
+    member_ref: string;
+};
+export type GongConnectionGrant = CompanyConnectionGrant;
+export type CompanyConnection<Provider extends string = string> = {
+    identity: CompanyCanonicalSourceIdentity<Provider>;
+    connection_ref: string;
+    connection_owner: "workspace";
+    connection_owner_role: "admin";
+    admin_ref: string;
+    connected: boolean;
+    members: string[];
+    session_refs: Array<{
+        session_ref: string;
+        member_ref: string;
+    }>;
+    grants: CompanyConnectionGrant[];
+    queued_lanes: Array<{
+        lane_ref: string;
+        member_ref: string;
+    }>;
+    unconsumed_receipts: Array<{
+        receipt_ref: string;
+        member_ref: string;
+    }>;
+};
+export type GongCompanyConnection = CompanyConnection<"gong">;
+export type ZoomCompanyConnection = CompanyConnection<"zoom">;
+export declare function connectCompanyConnection<Provider extends string>(input: {
+    identity: CompanyCanonicalSourceIdentity<Provider>;
+    connection_ref: string;
+    admin_ref: string;
+    presented_credential: {
+        issued_for: "company" | "personal";
+    };
+}): CompanyConnection<Provider>;
+export declare function disconnectCompanyConnection(state: CompanyConnection, actor_ref: string): CompanyConnection;
+export declare function revokeCompanyConnection(state: CompanyConnection, actor_ref: string): CompanyConnection;
+export declare function rotateCompanyConnection(state: CompanyConnection, actor_ref: string, next: {
+    connection_ref: string;
+}): CompanyConnection;
+export declare function assertCanApproveScope(state: CompanyConnection, actor_ref: string): void;
+export declare function removeWorkspaceMember(state: CompanyConnection, member_ref: string): {
+    connection: CompanyConnection;
+    lapsed: {
+        session_refs: string[];
+        grants: string[];
+        queued_lanes: string[];
+        unconsumed_receipts: string[];
+    };
+};
+export type TeamsCanonicalSourceIdentity = {
+    foo_workspace: string;
+    provider: "microsoft-teams";
+    tenant_id: string;
+};
+export declare function teamsCanonicalSourceIdentity(input: {
+    foo_workspace: string;
+    tenant_id: string;
+}): TeamsCanonicalSourceIdentity;
+export declare function teamsTenantSourceId(identity: TeamsCanonicalSourceIdentity): SourceId;
+export declare function teamsConnectionReady(input: {
+    connection_ref: string;
+    admin_ref: string;
+}): DiscoveryConnectionReady;
+export declare class TeamsMemberConnectionRefusal extends Error {
+    readonly action: "disconnect" | "rotate" | "revoke" | "transfer";
+    readonly actor_ref: string;
+    constructor(action: "disconnect" | "rotate" | "revoke" | "transfer", actor_ref: string);
+}
+export declare class TeamsPersonalCredentialRefused extends Error {
+    readonly handoff: string;
+    constructor();
+}
+export type TeamsConnectionGrant = {
+    grant_ref: string;
+    member_ref: string;
+};
+export type TeamsTenantConnection = {
+    identity: TeamsCanonicalSourceIdentity;
+    connection_ref: string;
+    connection_owner: "workspace";
+    connection_owner_role: "admin";
+    admin_ref: string;
+    connected: boolean;
+    members: string[];
+    session_refs: Array<{
+        session_ref: string;
+        member_ref: string;
+    }>;
+    grants: TeamsConnectionGrant[];
+    queued_lanes: Array<{
+        lane_ref: string;
+        member_ref: string;
+    }>;
+    unconsumed_receipts: Array<{
+        receipt_ref: string;
+        member_ref: string;
+    }>;
+};
+export declare function connectTeamsTenantConnection(input: {
+    identity: TeamsCanonicalSourceIdentity;
+    connection_ref: string;
+    admin_ref: string;
+    presented_credential: {
+        issued_for: "tenant" | "personal";
+    };
+}): TeamsTenantConnection;
+export declare function disconnectTeamsTenantConnection(state: TeamsTenantConnection, actor_ref: string): TeamsTenantConnection;
+export declare function revokeTeamsTenantConnection(state: TeamsTenantConnection, actor_ref: string): TeamsTenantConnection;
+export declare function rotateTeamsTenantConnection(state: TeamsTenantConnection, actor_ref: string, next: {
+    connection_ref: string;
+}): TeamsTenantConnection;
+export declare function assertCanApproveTeamsScope(state: TeamsTenantConnection, actor_ref: string): void;
+export declare function removeTeamsWorkspaceMember(state: TeamsTenantConnection, member_ref: string): {
+    connection: TeamsTenantConnection;
+    lapsed: {
+        session_refs: string[];
+        grants: string[];
+        queued_lanes: string[];
+        unconsumed_receipts: string[];
+    };
+};
+export declare function transferTeamsTenantConnection(state: TeamsTenantConnection, input: {
+    actor_ref: string;
+    next_admin_ref: string;
+    second_admin_confirmation: {
+        confirmed_by: string;
+    };
+}): TeamsTenantConnection;
+export declare class SourceWriteRefused extends Error {
+    constructor(action: string);
+}
+export declare function refuseSourceWrite(action: string): never;
+export declare function minimizeSummary(text: string): string;
+type PacketConnectionState = CompanyConnection | TeamsTenantConnection;
+export declare function loadPacketConnectionState(packetDir: string, source: Pick<SourceId, "provider" | "connection_id">): PacketConnectionState | null;
+export declare function savePacketConnectionState(packetDir: string, source: Pick<SourceId, "provider" | "connection_id">, state: PacketConnectionState): void;
+export type SlackScope = {
+    channel_ids: string[];
+    thread_ts?: string[];
+    window: {
+        start?: string;
+        end?: string;
+    };
+};
+export declare const SLACK_SCOPE_LIMITS: {
+    readonly policy_version: "slack-scope-0.1";
+    readonly max_channels_per_scope: 10;
+    readonly max_threads_per_scope: 25;
+};
+export declare const SLACK_CHANNEL_ID: RegExp;
+export declare const SLACK_THREAD_SELECTOR: RegExp;
+export declare function slackScopeValidationError(scope: SlackScope): string | null;
+export declare function approvalStates(packetDir: string): Map<string, {
+    state: ApprovalState;
+    scope?: string;
+    scopes: string[];
+}>;
+export type DiscoveredServer = {
+    ingress_path?: IngressPath;
+    provider: string;
+    connection_id: string;
+};
+export type DiscoverRow = SourceId & {
+    source_category: string;
+    evidence_class: EvidenceClass;
+    evidence_class_label: string;
+    sensitivity: Sensitivity;
+    approval_state: ApprovalState;
+    registered: boolean;
+    discovered_at: string;
+};
+export declare function loadSurface(surfacePath: string): DiscoveredServer[];
+export declare function discover(packetDir: string, servers: DiscoveredServer[], at: string): DiscoverRow[];
+export declare function approve(packetDir: string, id: SourceId, opts: {
+    packet: string;
+    scope: string;
+    by: string;
+    at: string;
+}): {
+    approved: boolean;
+    idempotent: boolean;
+};
+export declare function revoke(packetDir: string, id: SourceId, opts: {
+    packet: string;
+    by: string;
+    at: string;
+    priorScope?: string;
+}): {
+    revoked: boolean;
+    purged: number;
+    event_digest: string;
+};
+export type BrowserConnection = {
+    provider: string;
+    team_ref: string;
+    connection_ref: string;
+    revoked_at?: string | null;
+};
+export declare function browserConnectionRef(input: {
+    team_ref: string;
+    connection_ref: string;
+}): string;
+export declare function browserConnectionSourceId(conn: BrowserConnection): SourceId;
+export declare function browserConnectionReady(conn: BrowserConnection, admin_ref: string): DiscoveryConnectionReady;
+export type BrowserIngressStage = "liveness" | "approval";
+export type BrowserIngressDecision = {
+    allowed: true;
+    classification: Classification;
+    approval_state: "approved";
+} | {
+    allowed: false;
+    stage: BrowserIngressStage;
+    reason: string;
+    classification: Classification;
+    approval_state: ApprovalState;
+};
+export declare function browserIngressDecision(packetDir: string, conn: BrowserConnection): BrowserIngressDecision;
+export declare function recordSummary(packetDir: string, id: SourceId, opts: {
+    selection: string;
+    summary: string;
+    at: string;
+}): {
+    recorded: boolean;
+    reason?: string;
+};
+export type ClaimDirection = "supports" | "contradicts";
+export declare function recordClaim(packetDir: string, id: SourceId, opts: {
+    selection: string;
+    claim: string;
+    cites_task: string;
+    direction: ClaimDirection;
+    at: string;
+}): {
+    recorded: boolean;
+    reason?: string;
+};
+export declare function appendSourceConflictEvent(packetDir: string, opts: {
+    source_id: SourceId;
+    conflicts: Array<{
+        criterion_id: string;
+        status?: string;
+        check_kind?: string;
+    }>;
+    note: string;
+}, at: string): void;
+export declare function appendIntegrationRecord(packetDir: string, record: Record<string, unknown>): void;
+export type Receipt = {
+    schema_version: "0.1";
+    packet: string;
+    generated_at: string;
+    discovered: DiscoverRow[];
+    selected_and_read: Array<{
+        source_id: SourceId;
+        selection: string;
+        evidence_class_label: string;
+    }>;
+    claims: Array<{
+        source_id: SourceId;
+        selection: string;
+        cites_task: string;
+        direction: ClaimDirection;
+        evidence_class_label: string;
+    }>;
+    out_of_selection_scope: string;
+    excluded_after_evaluation: Array<{
+        source_id: SourceId;
+        reason: string;
+    }>;
+    summarized: number;
+    revoked: SourceId[];
+    coverage_note: string;
+};
+export declare function buildReceipt(packetDir: string, servers: DiscoveredServer[], at: string): Receipt;
+export type LinearSelection = {
+    unit: "issue" | "project";
+    connection_id: string;
+    external_id: string;
+    url: string;
+};
+export declare function parseLinearSource(spec: string): LinearSelection;
+export type LinearCandidate = {
+    source_id: SourceId & {
+        external_id: string;
+    };
+    evidence_authority: "approved-private-context";
+    title: string;
+    intent: string;
+    url: string;
+    state: string;
+};
+export type LinearPayload = {
+    title?: string;
+    description?: string;
+    state?: string;
+};
+export declare function buildLinearCandidate(selection: LinearSelection, payload: LinearPayload): LinearCandidate;
+export declare const LINEAR_READONLY_TOOLS: Set<string>;
+export declare function assertLinearReadOnlyTool(toolName: string): void;
+export type JiraRawIssue = {
+    key: string;
+    summary: string;
+    status: string;
+    assignee_display?: string;
+    updated: string;
+    remote_links?: Array<{
+        url?: string;
+        title?: string;
+    }>;
+};
+export declare function jiraIssueProject(key: string): string;
+export declare function jiraSiteHost(site: string): string;
+export declare function parseJiraSource(raw: unknown): JiraRawIssue;
+export type JiraScope = {
+    projects: string[];
+    jql?: string;
+    window: string;
+};
+export declare function parseJiraScope(raw: unknown): JiraScope;
+export declare function jiraScopeString(scope: JiraScope): string;
+export declare function parseJiraScopeString(scope: string): JiraScope;
+export declare function jiraScopeCoversIssue(scope: JiraScope, issue: JiraRawIssue): boolean;
+export type JiraCandidate = {
+    source_id: SourceId & {
+        external_id: string;
+    };
+    evidence_authority: "approved-private-context";
+    title: string;
+    intent: string;
+    url: string;
+    status: string;
+    updated: string;
+};
+export declare function buildJiraCandidate(input: {
+    site: string;
+    issue: JiraRawIssue;
+}): JiraCandidate;
+export declare const JIRA_READONLY_TOOLS: Set<string>;
+export declare function assertJiraReadOnlyTool(toolName: string): void;
+export type GithubSelection = {
+    unit: "pr" | "repo";
+    connection_id: string;
+    external_id: string;
+    owner: string;
+    repo: string;
+    pr?: number;
+    url: string;
+};
+export declare function parseGithubSource(spec: string): GithubSelection;
+export declare function githubSourceId(selection: GithubSelection): SourceId;
+export type GithubLinkage = {
+    linked: boolean;
+    authority: "foo-spec-trailer" | "none";
+    corroborating: string[];
+};
+export declare function githubLinkageForSpec(opts: {
+    specId: string;
+    commitMessages: string[];
+    branch?: string;
+    prBody?: string;
+}): GithubLinkage;
+export declare const GITHUB_READONLY_TOOLS: Set<string>;
+export declare function assertGithubReadOnlyTool(toolName: string): void;
+export type GithubPrEvidence = {
+    number?: number;
+    external_id?: string;
+    branch?: string;
+    body?: string;
+    title?: string;
+    commits?: Array<{
+        message?: string;
+        files?: string[];
+    }>;
+    merged?: boolean;
+    state?: string;
+    checks?: Array<{
+        name?: string;
+        conclusion?: string;
+    }>;
+    files_changed?: string[];
+};
+export type GithubFixture = GithubPrEvidence & {
+    pulls?: GithubPrEvidence[];
+};
+export type GithubSelectionReport = {
+    schema_version: "0.1";
+    packet: string;
+    source_id: SourceId;
+    unit: "pr" | "repo";
+    approval_state: ApprovalState;
+    linked: Array<{
+        external_id: string;
+        authority: GithubLinkage["authority"];
+        corroborating: string[];
+    }>;
+    unlinked_excluded: number;
+    note: string;
+};
+export declare function githubSelectionReport(opts: {
+    packet: string;
+    selection: GithubSelection;
+    approvalState: ApprovalState;
+    specId: string;
+    fixture?: GithubFixture;
+}): GithubSelectionReport;
+export {};