productfoo 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,339 @@
+export declare const CONNECTIONS_SCHEMA_VERSION = "0.1";
+export type DiscoveryConnectionRef = string;
+export type DiscoveryTargetRef = string;
+export type DiscoverySubjectRef = string;
+export type CanonicalSourceIdentity = {
+    foo_subject: DiscoverySubjectRef;
+    provider: string;
+    canonical_connection_key: string;
+};
+export declare function isConnectionRef(value: unknown): value is DiscoveryConnectionRef;
+export declare function isTargetRef(value: unknown): value is DiscoveryTargetRef;
+export declare function canonicalSourceIdentity(input: {
+    foo_subject: DiscoverySubjectRef;
+    provider: string;
+    provider_account_identity: string;
+}): CanonicalSourceIdentity;
+export type ConnectionRefMint = {
+    connection_ref: DiscoveryConnectionRef;
+    canonical: CanonicalSourceIdentity;
+};
+export declare function mintConnectionRef(input: {
+    foo_subject: DiscoverySubjectRef;
+    provider: string;
+    nango_connection_id: string;
+    server_salt?: string;
+}): ConnectionRefMint;
+export type ResolvedConnection = {
+    foo_subject: DiscoverySubjectRef;
+    provider: string;
+    nango_connection_id: string;
+    canonical: CanonicalSourceIdentity;
+};
+export type DiscoveryResolution = {
+    resolved: true;
+    identity: ResolvedConnection;
+} | {
+    resolved: false;
+    reason: "unknown_connection_ref" | "subject_mismatch";
+};
+export interface DiscoveryConnectionDirectory {
+    register(input: {
+        foo_subject: DiscoverySubjectRef;
+        provider: string;
+        nango_connection_id: string;
+        at: string;
+    }): ConnectionRefMint;
+    resolve(connection_ref: DiscoveryConnectionRef, acting: {
+        foo_subject: DiscoverySubjectRef;
+    }): DiscoveryResolution;
+}
+export declare function createInMemoryConnectionDirectory(): DiscoveryConnectionDirectory;
+export type DiscoveryLane = "study" | "inbox";
+export type DiscoveryTargetManifest = {
+    schema_version: "0.1";
+    kind: "discovery_target_manifest";
+    packet: string;
+    spec_id: string;
+    workspace_ref: string;
+    target_id: string;
+    lane: DiscoveryLane;
+    connection_ref: DiscoveryConnectionRef;
+    approved_selectors: string[];
+    approval_digest: string;
+    revocation_epoch: number;
+};
+export type DiscoveryManifestCheck = {
+    ok: true;
+    manifest: DiscoveryTargetManifest;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateDiscoveryTargetManifest(value: unknown): DiscoveryManifestCheck;
+export type DiscoveryHandoff = {
+    kind: string;
+    url?: string;
+    resume_command?: string;
+    requires_human: boolean;
+};
+export type DiscoveryPendingTargetRequest = {
+    schema_version: "0.1";
+    kind: "discovery_target_pending_request";
+    subject_ref: DiscoverySubjectRef;
+    manifest: DiscoveryTargetManifest;
+    requested_at: string;
+    state: "pending";
+};
+export type DiscoveryRegisterTargetResult = {
+    status: "needs_service_grant";
+    pending_request_id: string;
+    handoff: DiscoveryHandoff;
+    next_actions: string[];
+} | {
+    status: "invalid";
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+};
+export type DiscoveryConfirmationDecision = {
+    confirmed: true;
+    confirmed_by: string;
+    confirmed_at: string;
+    confirmed_via: string;
+} | {
+    confirmed: false;
+    reason: "deferred" | "refused";
+    note?: string;
+};
+export interface DiscoveryConfirmationSeam {
+    confirmTargetManifest(manifest: DiscoveryTargetManifest): Promise<DiscoveryConfirmationDecision>;
+}
+export type DiscoverySuspendTargetAck = {
+    suspended: true;
+    target_ref: DiscoveryTargetRef;
+    revocation_epoch: number;
+} | {
+    suspended: false;
+    target_ref: string;
+    reason: "unknown_target_ref" | "subject_mismatch" | "service_unreachable" | "invalid_request";
+    message: string;
+};
+export interface DiscoveryServiceEndpoint {
+    registerPendingTarget(input: {
+        subject_ref: DiscoverySubjectRef;
+        manifest: DiscoveryTargetManifest;
+        requested_at: string;
+    }): Promise<{
+        stored: true;
+        pending_request_id: string;
+    } | {
+        stored: false;
+        reason: string;
+        message: string;
+    }>;
+    confirmTargetRegistration(input: {
+        manifest: DiscoveryTargetManifest;
+        confirmation: DiscoveryConfirmationDecision;
+        at: string;
+    }): Promise<{
+        confirmed_registration: true;
+        target_ref: DiscoveryTargetRef;
+        grant: DiscoveryServiceGrant;
+    } | {
+        confirmed_registration: false;
+        reason: string;
+        message: string;
+    }>;
+    suspendTarget(input: {
+        target_ref: string;
+        acting_subject: DiscoverySubjectRef;
+        revocation_event_digest: string;
+        requested_by: string;
+        at: string;
+    }): Promise<DiscoverySuspendTargetAck>;
+}
+export declare class DiscoveryServiceUnreachableError extends Error {
+    readonly op: "register" | "confirm" | "suspend";
+    constructor(op: "register" | "confirm" | "suspend");
+}
+export declare function createUnreachableDiscoveryService(): DiscoveryServiceEndpoint;
+export declare function registerDiscoveryTarget(input: {
+    subject_ref: DiscoverySubjectRef;
+    service: DiscoveryServiceEndpoint;
+    manifest: unknown;
+    at: string;
+}): Promise<DiscoveryRegisterTargetResult>;
+export type DiscoveryConfirmTargetResult = {
+    status: "ready";
+    target_ref: DiscoveryTargetRef;
+    grant: DiscoveryServiceGrant;
+    next_actions: string[];
+} | {
+    status: "needs_service_grant";
+    reason: string;
+    handoff: DiscoveryHandoff;
+} | {
+    status: "invalid";
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+};
+export declare function confirmDiscoveryTargetRegistration(input: {
+    service: DiscoveryServiceEndpoint;
+    seam: DiscoveryConfirmationSeam;
+    manifest: unknown;
+    at: string;
+}): Promise<DiscoveryConfirmTargetResult>;
+export type DiscoveryGrantBudget = {
+    max_operations: number;
+    window: "day";
+};
+export type DiscoveryServiceGrant = {
+    schema_version: "0.1";
+    kind: "discovery_service_grant";
+    subject_ref: DiscoverySubjectRef;
+    workspace_ref: string;
+    target_ref: DiscoveryTargetRef;
+    target_id: string;
+    lane: DiscoveryLane;
+    connection_ref: DiscoveryConnectionRef;
+    approved_selectors: string[];
+    approval_digest: string;
+    revocation_epoch: number;
+    issued_at: string;
+    expires_at: string;
+    budget: DiscoveryGrantBudget;
+};
+export type DiscoveryGrantCheck = {
+    ok: true;
+    grant: DiscoveryServiceGrant;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateDiscoveryServiceGrant(value: unknown): DiscoveryGrantCheck;
+export type DiscoveryBoundaryExpectation = {
+    subject_ref: DiscoverySubjectRef;
+    connection_ref: DiscoveryConnectionRef;
+    workspace_ref: string;
+    target_id: string;
+    lane: DiscoveryLane;
+    approval_digest: string;
+    revocation_epoch: number;
+    selector?: string;
+};
+export type DiscoveryBoundaryFailureReason = "unknown_grant" | "subject_mismatch" | "connection_mismatch" | "workspace_mismatch" | "target_mismatch" | "lane_mismatch" | "approval_mismatch" | "stale_revocation_epoch" | "grant_expired" | "selector_out_of_scope" | "budget_exhausted";
+export type DiscoveryBoundaryCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: DiscoveryBoundaryFailureReason;
+    message: string;
+};
+export declare function recheckDiscoveryAccessBoundary(input: {
+    grant?: DiscoveryServiceGrant | unknown;
+    expected: DiscoveryBoundaryExpectation;
+    operations_used?: number;
+    now: string;
+}): DiscoveryBoundaryCheck;
+export declare class DiscoveryBoundaryRefused extends Error {
+    readonly check: DiscoveryBoundaryCheck & {
+        ok: false;
+    };
+    constructor(check: DiscoveryBoundaryCheck & {
+        ok: false;
+    });
+}
+export declare function assertDiscoveryBoundary(check: DiscoveryBoundaryCheck): void;
+export declare function guardedDiscoveryAccess<T>(check: DiscoveryBoundaryCheck, access: () => Promise<T>): Promise<T>;
+export declare function createInMemoryDiscoveryService(opts?: {
+    server_salt?: string;
+    directory?: DiscoveryConnectionDirectory;
+    grant_ttl_ms?: number;
+    default_budget?: DiscoveryGrantBudget;
+}): DiscoveryServiceEndpoint & {
+    currentRevocationEpoch(target_ref: DiscoveryTargetRef): number | null;
+    operationsUsed(target_ref: DiscoveryTargetRef): number | null;
+    recordOperation(target_ref: DiscoveryTargetRef): void;
+    pendingRequests(): DiscoveryPendingTargetRequest[];
+};
+export type DiscoveryTargetSuspensionState = {
+    epoch: number;
+    state: "acknowledged" | "revocation_pending";
+    recorded_at: string;
+};
+export type DiscoveryRegisteredTarget = {
+    schema_version: "0.1";
+    kind: "discovery_registered_target";
+    subject_ref: DiscoverySubjectRef;
+    target_ref: DiscoveryTargetRef;
+    workspace_ref: string;
+    target_id: string;
+    lane: DiscoveryLane;
+    packet: string;
+    spec_id: string;
+    provider: string;
+    connection_id: string;
+    connection_ref: DiscoveryConnectionRef;
+    approved_selectors: string[];
+    approval_digest: string;
+    revocation_epoch: number;
+    registered_at: string;
+    suspension: DiscoveryTargetSuspensionState | null;
+};
+export declare function recordDiscoveryTargetRegistration(localRoot: string, input: {
+    manifest: DiscoveryTargetManifest;
+    confirmation: {
+        confirmed_by: string;
+        confirmed_at: string;
+        confirmed_via: string;
+    };
+    result: {
+        target_ref: DiscoveryTargetRef;
+        grant: DiscoveryServiceGrant;
+    };
+    local: {
+        subject_ref: DiscoverySubjectRef;
+        provider: string;
+        connection_id: string;
+    };
+    at: string;
+}): DiscoveryRegisteredTarget;
+export declare function loadDiscoveryRegisteredTargets(localRoot: string): DiscoveryRegisteredTarget[];
+export declare function findDiscoveryTargetsForApproval(localRoot: string, approval: {
+    provider: string;
+    connection_id: string;
+}): DiscoveryRegisteredTarget[];
+export type DiscoverySuspendFanOutOutcome = {
+    target_ref: DiscoveryTargetRef;
+    target_id: string;
+    status: "suspended";
+    revocation_epoch: number;
+} | {
+    target_ref: DiscoveryTargetRef;
+    target_id: string;
+    status: "revocation_pending";
+    reason: string;
+    message: string;
+};
+export type DiscoverySuspendFanOutResult = {
+    registered: number;
+    acknowledged: number;
+    pending: number;
+    outcomes: DiscoverySuspendFanOutOutcome[];
+};
+export declare function fanOutDiscoveryTargetSuspension(input: {
+    localRoot: string;
+    provider: string;
+    connection_id: string;
+    /** Limit the fan-out to one target (a single study's revoke, #898);
+     *  omitted, every target registered from the approval is suspended. */
+    target_id?: string;
+    revocation_event_digest: string;
+    requested_by: string;
+    service?: DiscoveryServiceEndpoint;
+    at: string;
+}): Promise<DiscoverySuspendFanOutResult>;