@dxos/protocols 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/dist/src/edge/edge.d.ts

@@ -0,0 +1,698 @@
+import * as Schema from 'effect/Schema';
+import { SpaceId } from '@dxos/keys';
+/**
+ * HTTP header sent on every Edge request to classify traffic for metering.
+ */
+export declare const EDGE_CLIENT_TAG_HEADER = "X-DXOS-Client-Tag";
+/**
+ * HTTP header sent on every Edge request to provide a BYOK (Bring Your Own Key) for AI services.
+ */
+export declare const BYOK_HEADER = "X-BYOK";
+export declare enum EdgeService {
+    AUTOMERGE_REPLICATOR = "automerge-replicator",
+    SUBDUCTION_REPLICATOR = "subduction-replicator",
+    /**
+     * Control feed replicator (hypercore append only logs) for the space.
+     */
+    FEED_REPLICATOR = "feed-replicator",
+    /**
+     * Feed replicator (ordered data list) for the space.
+     */
+    QUEUE_REPLICATOR = "queue-replicator",
+    SWARM = "swarm",
+    SIGNAL = "signal",
+    STATUS = "status"
+}
+export type EdgeSuccess<T> = {
+    success: true;
+    data: T;
+};
+declare const _SerializedError: Schema.Struct<{
+    name: Schema.optional<typeof Schema.String>;
+    message: Schema.optional<typeof Schema.String>;
+    context: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Any>>;
+    stack: Schema.optional<typeof Schema.String>;
+    cause: Schema.optional<Schema.suspend<SerializedError, SerializedError, never>>;
+}>;
+export interface SerializedError extends Schema.Schema.Type<typeof _SerializedError> {
+}
+export declare const SerializedError: Schema.Schema<SerializedError, SerializedError, never>;
+export type EdgeErrorData = {
+    type: string;
+} & Record<string, any>;
+/**
+ * This is the shape of the error response from the Edge service,
+ * when the error is gracefully handled, the Response will be an object with this shape and have status code 200.
+ */
+export type EdgeFailure = {
+    /**
+     * Branded Type.
+     */
+    success: false;
+    /**
+     * An explanation of why the call failed. Used mostly for logging and monitoring.
+     */
+    message: string;
+    /**
+     * Cause Error captured on the EDGE service to aid debugging on the client.
+     */
+    error?: SerializedError;
+    /**
+     * Information that can be used to retry the request such that it will succeed, for example:
+     * 1. { type: 'auth_required', challenge: string }
+     *    Requires retrying the request with challenge signature included.
+     * 2. { type: 'user_confirmation_required', dialog: { title: string, message: string, confirmation_payload: string } }
+     *    Requires showing a confirmation dialog to a user and retrying the request with confirmation_payload included
+     *    if the user confirms.
+     * When data is returned simply retrying the request won't have any effect.
+     * EdgeHttpClient should parse well-known data into Error types and throw.
+     */
+    data?: EdgeErrorData;
+};
+/**
+ * Represents a body response from the Edge service.
+ */
+export type EdgeEnvelope<T> = EdgeSuccess<T> | EdgeFailure;
+/**
+ * Use this to create a response from the Edge service.
+ */
+export declare const EdgeResponse: Readonly<{
+    success: <T>(data: T, status?: number) => Response;
+    failure: ({ message, error, errorEncoded, data, shouldRetryAfter, status, }: {
+        /**
+         * An explanation of why the call failed. Used mostly for logging and monitoring.
+         */
+        message: string;
+        /**
+         * Error that caused the failure.
+         * Useful for debugging.
+         *
+         * Use only one of the fields `error` or `errorEncoded`.s
+         */
+        error?: Error;
+        /**
+         * Encoded Error that caused the failure.
+         * Useful for debugging.
+         *
+         * Use only one of the fields `error` or `errorEncoded`.
+         */
+        errorEncoded?: SerializedError;
+        /**
+         * Information that can be used to retry the request such that it will succeed, for example:
+         * 1. { type: 'auth_required', challenge: string }
+         *    Requires retrying the request with challenge signature included.
+         * 2. { type: 'user_confirmation_required', dialog: { title: string, message: string, confirmation_payload: string } }
+         *    Requires showing a confirmation dialog to a user and retrying the request with confirmation_payload included
+         *    if the user confirms.
+         * When data is returned simply retrying the request won't have any effect.
+         * EdgeHttpClient should parse well-known data into Error types and throw.
+         */
+        data?: EdgeErrorData;
+        /**
+         * If provided, this request will be marked as retryable and the client will wait for the specified number of milliseconds before retrying.
+         * If not provided, the client will not retry the request.
+         */
+        shouldRetryAfter?: number;
+        /**
+         * Status code of the response.
+         * @default 500
+         */
+        status?: number;
+    }) => Response;
+}>;
+export type GetNotarizationResponseBody = {
+    awaitingNotarization: {
+        credentials: string[];
+    };
+};
+export type ExecuteWorkflowResponseBody = {
+    success: boolean;
+    reason?: string;
+    output?: any;
+};
+export type PostNotarizationRequestBody = {
+    credentials: string[];
+};
+export type JoinSpaceRequest = {
+    invitationId: string;
+    identityKey: string;
+    /**
+     * Base64 encoded signed challenge.
+     * Used to verify the IdentityKey in case of `invitation.authMethod === Invitation.AuthMethod.KNOWN_PUBLIC_KEY`
+     */
+    signature?: string;
+};
+export type JoinSpaceResponseBody = {
+    spaceMemberCredential: string;
+    spaceGenesisFeedKey: string;
+};
+export type RecoverIdentitySignature = string | {
+    signature: string;
+    clientDataJson: string;
+    authenticatorData: string;
+};
+export type RecoverIdentityRequest = {
+    deviceKey: string;
+    controlFeedKey: string;
+    lookupKey?: string;
+    signature?: RecoverIdentitySignature;
+    token?: string;
+    /**
+     * One-time proof minted by kms-service after a successful OAuth recovery flow.
+     * When provided, db-service redeems the proof to obtain the bound identityKey directly
+     * and `lookupKey`/`signature` are not required.
+     */
+    recoveryProof?: string;
+};
+export type RecoverIdentityResponseBody = {
+    identityKey: string;
+    haloSpaceKey: string;
+    genesisFeedKey: string;
+    deviceAuthCredential: string;
+};
+export type CreateAgentRequestBody = {
+    identityKey: string;
+    haloSpaceId: SpaceId;
+    haloSpaceKey: string;
+};
+export type CreateAgentResponseBody = {
+    deviceKey: string;
+    feedKey: string;
+};
+export type GetAgentStatusResponseBody = {
+    agent: {
+        deviceKey?: string;
+        status: EdgeAgentStatus;
+    };
+};
+export type UploadFunctionRequest = {
+    name?: string;
+    version: string;
+    ownerPublicKey: string;
+    entryPoint: string;
+    assets: Record<string, Uint8Array>;
+    /**
+     * Runtime in Edge that will be used to run the function.
+     * Runtime cannot be changed once the function was deployed.
+     * @default Runtime.WORKERS_FOR_PLATFORMS
+     */
+    runtime?: FunctionRuntimeKind;
+};
+/**
+ * Note: Do not change the values of these enums, this values are stored in the FunctionVersions database.
+ */
+export declare const FunctionRuntimeKind: Schema.Enums<{
+    WORKERS_FOR_PLATFORMS: string;
+    WORKER_LOADER: string;
+}>;
+export type FunctionRuntimeKind = Schema.Schema.Type<typeof FunctionRuntimeKind>;
+export type UploadFunctionResponseBody = {
+    functionId: string;
+    version: string;
+    meta: {
+        key?: string;
+        name?: string;
+        description?: string;
+        /**
+         * JSON Schema for the input of the function.
+         */
+        inputSchema?: object;
+        /**
+         * JSON Schema for the output of the function.
+         */
+        outputSchema?: object;
+    };
+};
+export type CreateSpaceRequest = {
+    /**
+     * HEX encoded public key of the agent.
+     */
+    agentKey: string;
+};
+export type CreateSpaceResponseBody = {
+    /**
+     * HEX encoded public key of the space.
+     */
+    spaceKey: string;
+    spaceId: SpaceId;
+    automergeRoot: string;
+};
+export declare enum EdgeAgentStatus {
+    ACTIVE = "active",
+    INACTIVE = "inactive",
+    NOT_FOUND = "not_found"
+}
+export type EdgeAuthChallenge = {
+    type: 'auth_challenge';
+    challenge: string;
+};
+export declare enum OAuthProvider {
+    ATLASSIAN = "atlassian",
+    ATPROTO = "atproto",
+    /** @deprecated Use ATPROTO instead. */
+    BLUESKY = "bluesky",
+    DISCORD = "discord",
+    GITHUB = "github",
+    GOOGLE = "google",
+    LINEAR = "linear",
+    NOTION = "notion",
+    SLACK = "slack",
+    TRELLO = "trello"
+}
+export declare const InitiateOAuthFlowRequestSchema: Schema.Struct<{
+    provider: Schema.Enums<typeof OAuthProvider>;
+    spaceId: Schema.refine<string & {
+        __SpaceId: true;
+    }, Schema.Schema<unknown, string, never>>;
+    accessTokenId: typeof Schema.String;
+    scopes: Schema.mutable<Schema.Array$<typeof Schema.String>>;
+    noRefresh: Schema.optional<typeof Schema.Boolean>;
+    loginHint: Schema.optional<typeof Schema.String>;
+    nativeAppRedirect: Schema.optional<typeof Schema.Boolean>;
+    registerRecovery: Schema.optional<typeof Schema.Boolean>;
+    identityKey: Schema.optional<typeof Schema.String>;
+    purpose: Schema.optional<Schema.Literal<["register", "recovery"]>>;
+}>;
+export type InitiateOAuthFlowRequest = Schema.Schema.Type<typeof InitiateOAuthFlowRequestSchema>;
+export type InitiateOAuthFlowResponse = {
+    authUrl: string;
+};
+export type OAuthFlowResult = {
+    success: true;
+    accessToken: string;
+    accessTokenId: string;
+    recoveryProof?: string;
+} | {
+    success: false;
+    reason: string;
+};
+/**
+ * Completes OAuth recovery registration for an existing identity: routes the OAuth refresh token
+ * into the personal space and writes the recovery binding.
+ */
+export type CompleteOAuthRegistrationRequest = {
+    registrationToken: string;
+    identityKey: string;
+    spaceKey: string;
+};
+export type CompleteOAuthRegistrationResponse = {
+    email?: string;
+    provider: OAuthProvider;
+    accessTokenId: string;
+    accessToken: string;
+    expiresInSeconds: number;
+    scopes: string[];
+    identifier: string;
+};
+export declare enum EdgeWebsocketProtocol {
+    V0 = "edge-ws-v0",
+    /**
+     * Enables message framing and muxing by service-id.
+     */
+    V1 = "edge-ws-v1"
+}
+export type EdgeStatus = {
+    problems: string[];
+    agent: {
+        agentStatus?: string;
+        agentKey?: string;
+        haloSpaceId?: SpaceId;
+        fetchError?: string;
+    };
+    router: {
+        connectedDevices?: {
+            peerKey: string;
+            topics: string[];
+        }[];
+        metrics?: {
+            sentMessages: number;
+            receivedMessages: number;
+            sentBytes: number;
+            receivedBytes: number;
+            failedMessages: number;
+            failedBytes: number;
+        };
+        fetchError?: string;
+    };
+    spaces: {
+        data: Record<SpaceId, {
+            diagnostics?: any & {
+                redFlags: string[];
+            };
+            fetchError?: string;
+        }>;
+        fetchError?: string;
+    };
+};
+export type ImportBundleRequest = {
+    bundle: {
+        /**
+         * DocumentId.
+         */
+        documentId: string;
+        /**
+         * Encoded mutation.
+         */
+        mutation: string;
+        /**
+         * Heads of the document.
+         */
+        heads: string[];
+    }[];
+};
+export type ExportBundleRequest = {
+    /**
+     * DocumentId -> Heads (decoded heads since which we want to export).
+     */
+    docHeads: Record<string, string[]>;
+};
+export type ExportBundleResponse = {
+    bundle: {
+        /**
+         * DocumentId.
+         */
+        documentId: string;
+        /**
+         * Encoded mutation.
+         */
+        mutation: string;
+    }[];
+};
+export declare const DocumentCodec: Readonly<{
+    encode: (doc: Uint8Array) => string;
+    decode: (doc: string) => Uint8Array<ArrayBuffer>;
+}>;
+/**
+ * Codec for serializing and deserializing Edge Errors.
+ */
+export declare const ErrorCodec: Readonly<{
+    encode: (err: Error, depth?: number) => SerializedError;
+    decode: (serializedError: SerializedError, depth?: number) => Error;
+}>;
+/**
+ * Codec for serializing and deserializing Edge unhandled HTTP errors.
+ */
+export declare const EdgeHttpErrorCodec: Readonly<{
+    encode: (err: Error) => Response;
+    decode: (response: Response) => Promise<Error | undefined>;
+}>;
+export type ListSpacesRequest = {
+    limit?: number;
+    cursor?: string;
+    order?: 'asc' | 'desc';
+};
+export type ListSpacesResponse = {
+    spaces: SpaceActivityEntry[];
+    cursor?: string;
+    limit: number;
+};
+export type ListActiveIdentitiesRequest = {
+    cursor?: string;
+    limit?: number;
+};
+export type ListActiveIdentitiesResponse = {
+    identities: {
+        identityKey: string;
+        haloSpaceId: string | null;
+        createdAt: string | null;
+        agentKey: string | null;
+        hasRecovery: boolean;
+    }[];
+    cursor?: string;
+    complete: boolean;
+    totalCount: number;
+};
+export type InspectSpaceRequest = {
+    spaceId: string;
+};
+export type InspectSpaceResponse = {
+    spaceId: string;
+    metadata: {
+        createdAt: string;
+        identityKey?: string;
+        status?: 'active' | 'deleting';
+    } | null;
+    members: {
+        count: number;
+        list: {
+            identityKey: string;
+            role?: string;
+            agentKey?: string;
+        }[];
+    };
+    controlFeeds: {
+        replicationProgress: {
+            [feedKey: string]: {
+                replicated: number;
+                processed: number;
+            };
+        };
+    };
+    echo: {
+        dataFeeds: {
+            count: number;
+            totalBlocks: number;
+            byNamespace: {
+                namespace: string;
+                feeds: {
+                    feedId: string;
+                    blockCount: number;
+                }[];
+            }[];
+        };
+        documentCount: number;
+        objectCount: number;
+        deletedObjectCount: number;
+        indexedDocumentCount: number;
+        objectsByType: {
+            typeURI: string;
+            count: number;
+        }[];
+        indexerStatus: {
+            indexingInProgress: boolean;
+            cursors: {
+                indexName: string;
+                sourceName: string;
+                resourceId: string | null;
+                cursor: string | number;
+            }[];
+            totalChanges: number;
+        };
+    };
+    usageInLast30Days: {
+        lastActivity: string | null;
+        wsEvents: number;
+        httpEvents: number;
+        totalEvents: number;
+    } | null;
+    durableObjects: {
+        type: string;
+        doId: string;
+    }[];
+};
+export type InspectIdentityRequest = {
+    identityKey: string;
+};
+export type InspectIdentityResponse = {
+    identityKey: string;
+    agentKey: string | null;
+    haloSpaceId: string | null;
+    hasRecovery: boolean;
+    routerDoId: string;
+    agentDoId: string | null;
+    ownedFunctions: {
+        id: string;
+        name: string;
+        versionCount: number;
+    }[];
+    spaces: InspectSpaceResponse[];
+};
+/** Matches the SerializedSpace format from @dxos/echo-client, extended with spaceId. */
+export type SpaceExportPayload = {
+    version: number;
+    timestamp: string;
+    spaceId: string;
+    objects: Record<string, unknown>[];
+};
+export type SpaceActivityEntry = {
+    spaceId: string;
+    lastActivity: string;
+    totalEvents: number;
+    metadata: {
+        createdAt: string;
+        identityKey?: string;
+        status?: 'active' | 'deleting';
+    } | null;
+};
+export type SpaceExportResult = {
+    spaceId: string;
+    downloadPath: string;
+    downloadUrl: string;
+    expiresAt: string;
+    objectCount: number;
+    sizeBytes: number;
+};
+export type ExportSpaceRequest = {
+    spaceId: string;
+    origin: string;
+};
+export type DeleteSpaceRequest = {
+    spaceId: string;
+};
+export type DeleteSpaceResponse = {
+    status: string;
+    spaceId: string;
+};
+export type DeleteIdentityRequest = {
+    identityKey: string;
+};
+export type DeleteIdentityResponse = {
+    status: string;
+    identityKey: string;
+};
+export declare const INVITATION_CODE_LENGTH = 8;
+export declare const DEFAULT_INVITATIONS_PER_ACCOUNT = 5;
+/** Crockford base32 alphabet (no I, L, O, U). Case-insensitive on the wire. */
+export declare const INVITATION_CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const InvitationCodeSchema: Schema.filter<typeof Schema.String>;
+export declare const CheckEmailExistsRequestSchema: Schema.Struct<{
+    email: typeof Schema.String;
+}>;
+export type CheckEmailExistsRequest = Schema.Schema.Type<typeof CheckEmailExistsRequestSchema>;
+export type CheckEmailExistsResponse = {
+    exists: boolean;
+};
+export declare const ValidateInvitationCodeRequestSchema: Schema.Struct<{
+    code: Schema.filter<typeof Schema.String>;
+}>;
+export type ValidateInvitationCodeRequest = Schema.Schema.Type<typeof ValidateInvitationCodeRequestSchema>;
+export type ValidateInvitationCodeResponse = {
+    valid: boolean;
+};
+/**
+ * Body of `POST /account/login`. Existing-account email recovery only --
+ * unlike `/account/signup`, this never creates new identities or waitlist rows.
+ */
+export declare const LoginRequestSchema: Schema.Struct<{
+    email: typeof Schema.String;
+    identityDid: Schema.optional<typeof Schema.String>;
+    identityKey: Schema.optional<typeof Schema.String>;
+}>;
+export type LoginRequest = Schema.Schema.Type<typeof LoginRequestSchema>;
+/**
+ * Response from `POST /account/login`. The shape is identical regardless of
+ * whether the email is registered, so the endpoint is safe against enumeration.
+ * Regular emails are delivered out-of-band and the response is `{}`.
+ */
+export declare const LoginResponseSchema: Schema.Struct<{
+    token: Schema.optional<typeof Schema.String>;
+    needsIdentity: Schema.optional<typeof Schema.Boolean>;
+    admitted: Schema.optional<typeof Schema.Boolean>;
+}>;
+export type LoginResponse = Schema.Schema.Type<typeof LoginResponseSchema>;
+export declare const RedeemInvitationCodeRequestSchema: Schema.Struct<{
+    code: Schema.optional<Schema.filter<typeof Schema.String>>;
+    identityDid: Schema.optional<typeof Schema.String>;
+    /** Raw hex public key, stored alongside the DID for the magic-link recovery flow. */
+    identityKey: Schema.optional<typeof Schema.String>;
+    email: typeof Schema.String;
+}>;
+export type RedeemInvitationCodeRequest = Schema.Schema.Type<typeof RedeemInvitationCodeRequestSchema>;
+export type RedeemInvitationCodeResponse = {
+    accountId: string;
+    emailVerificationSent: boolean;
+} | {
+    needsIdentity: true;
+};
+export declare const GetAccountResponseSchema: Schema.Struct<{
+    identityDid: typeof Schema.String;
+    email: typeof Schema.String;
+    emailVerified: typeof Schema.Boolean;
+    /** ISO timestamp. */
+    createdAt: typeof Schema.String;
+    invitationsRemaining: typeof Schema.Number;
+}>;
+export type GetAccountResponse = Schema.Schema.Type<typeof GetAccountResponseSchema>;
+export declare const AccountInvitationSchema: Schema.Struct<{
+    code: typeof Schema.String;
+    /** ISO timestamp. */
+    createdAt: typeof Schema.String;
+    redeemedByIdentityDid: Schema.optional<typeof Schema.String>;
+    /** ISO timestamp. */
+    redeemedAt: Schema.optional<typeof Schema.String>;
+}>;
+export type AccountInvitation = Schema.Schema.Type<typeof AccountInvitationSchema>;
+export declare const ListAccountInvitationsResponseSchema: Schema.Struct<{
+    invitations: Schema.Array$<Schema.Struct<{
+        code: typeof Schema.String;
+        /** ISO timestamp. */
+        createdAt: typeof Schema.String;
+        redeemedByIdentityDid: Schema.optional<typeof Schema.String>;
+        /** ISO timestamp. */
+        redeemedAt: Schema.optional<typeof Schema.String>;
+    }>>;
+}>;
+export type ListAccountInvitationsResponse = Schema.Schema.Type<typeof ListAccountInvitationsResponseSchema>;
+export type IssueInvitationResponse = {
+    code: string;
+};
+export type ResendVerificationEmailResponse = {
+    sent: boolean;
+    cooldownSecondsRemaining?: number;
+};
+/**
+ * Submitted by users without an Account who want to request access. Captured
+ * by Hub for admin follow-up (e.g. mailing list, Discord notification).
+ */
+export declare const RequestAccessRequestSchema: Schema.Struct<{
+    email: typeof Schema.String;
+    /** Optional: identity DID the user is currently signed in as. */
+    identityDid: Schema.optional<typeof Schema.String>;
+    /** Optional free-form message from the requester. */
+    message: Schema.optional<typeof Schema.String>;
+}>;
+export type RequestAccessRequest = Schema.Schema.Type<typeof RequestAccessRequestSchema>;
+export type RequestAccessResponse = {
+    received: boolean;
+};
+export type AdminListAccountsResponse = {
+    accounts: GetAccountResponse[];
+};
+export declare const AdminGrantInvitationsRequestSchema: Schema.Struct<{
+    identityDid: typeof Schema.String;
+    count: typeof Schema.Number;
+}>;
+export type AdminGrantInvitationsRequest = Schema.Schema.Type<typeof AdminGrantInvitationsRequestSchema>;
+export declare const AdminCreateInvitationCodesRequestSchema: Schema.Struct<{
+    count: typeof Schema.Number;
+    note: Schema.optional<typeof Schema.String>;
+}>;
+export type AdminCreateInvitationCodesRequest = Schema.Schema.Type<typeof AdminCreateInvitationCodesRequestSchema>;
+export type AdminCreateInvitationCodesResponse = {
+    codes: string[];
+};
+export type AdminListInvitationCodesResponse = {
+    codes: Array<{
+        code: string;
+        /** ISO timestamp. */
+        createdAt: string;
+        note?: string;
+        issuedByIdentityDid?: string;
+        redeemedByIdentityDid?: string;
+        /** ISO timestamp. */
+        redeemedAt?: string;
+        /** ISO timestamp. Set when revoked. */
+        revokedAt?: string;
+    }>;
+};
+export declare const AdminRevokeInvitationCodeRequestSchema: Schema.Struct<{
+    code: Schema.filter<typeof Schema.String>;
+}>;
+export type AdminRevokeInvitationCodeRequest = Schema.Schema.Type<typeof AdminRevokeInvitationCodeRequestSchema>;
+/**
+ * Account/invitation-related variants placed in `EdgeFailure.data.type`.
+ * EdgeErrorData is open-ended; these are documentation for known values.
+ */
+export type AccountErrorType = 'invitation_code_invalid' | 'invitation_code_already_redeemed' | 'invitation_code_revoked' | 'email_already_registered' | 'identity_already_associated' | 'no_invitations_remaining' | 'identity_not_associated_with_account' | 'no_account' | 'rate_limited';
+export {};
+//# sourceMappingURL=edge.d.ts.map