@sealant/api-contracts-next 0.39.0-next.754 → 0.40.0-next.756

package/dist/connected-account-selector.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The account selector that resolves to the owner's chosen default for a provider. Its own
+ * dependency-free entry so the bundled CLI can import it without the HttpApi contract.
+ */
+export declare const DEFAULT_ACCOUNT_SELECTOR = "default";

package/dist/connected-account-selector.js

@@ -0,0 +1,5 @@
+/**
+ * The account selector that resolves to the owner's chosen default for a provider. Its own
+ * dependency-free entry so the bundled CLI can import it without the HttpApi contract.
+ */
+export const DEFAULT_ACCOUNT_SELECTOR = "default";

package/dist/core-api/connected-accounts.d.ts

@@ -44,12 +44,30 @@ export declare const connectedAccountSummarySchema: Schema.Struct<{
         /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
         readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
     }>;
+    /** Whether this is the owner's default for its provider. Absent from older control planes. */
+    readonly isDefault: Schema.optional<Schema.Boolean>;
+    /**
+     * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+     * stores different bytes. Absent from older control planes.
+     */
+    readonly credentialRevision: Schema.optional<Schema.Int>;
 }>;
 export type ConnectedAccountSummary = typeof connectedAccountSummarySchema.Type;
 export declare const createConnectedAccountRequestSchema: Schema.Struct<{
     readonly ownerUserId: Schema.String;
     readonly provider: Schema.Literals<readonly ["claude", "codex", "github"]>;
+    /**
+     * The account to connect or replace by name; a new name is a new account, and `default` names
+     * the owner's chosen default. The owner's first account for the provider is named `default`
+     * whatever this says. With neither `name` nor `accountId` (or `default` while none is chosen),
+     * the owner's only account is replaced, and with several the connect is refused (`409`,
+     * `connected-account-ambiguous`, with `candidateAccountIds`).
+     */
     readonly name: Schema.optional<Schema.String>;
+    /** Replace this account (the owner's, of `provider`). Not with `name`. */
+    readonly accountId: Schema.optional<Schema.String>;
+    /** Make the connected account the owner's default for the provider, in the same write. */
+    readonly makeDefault: Schema.optional<Schema.Boolean>;
     readonly secret: Schema.String;
 }>;
 export type CreateConnectedAccountRequest = typeof createConnectedAccountRequestSchema.Type;
@@ -81,13 +99,64 @@ export declare const listConnectedAccountsResponseSchema: Schema.Struct<{
             /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
             readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
         }>;
+        /** Whether this is the owner's default for its provider. Absent from older control planes. */
+        readonly isDefault: Schema.optional<Schema.Boolean>;
+        /**
+         * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+         * stores different bytes. Absent from older control planes.
+         */
+        readonly credentialRevision: Schema.optional<Schema.Int>;
     }>>;
 }>;
 export type ListConnectedAccountsResponse = typeof listConnectedAccountsResponseSchema.Type;
 export declare const markConnectedAccountInvalidRequestSchema: Schema.Struct<{
     readonly ownerUserId: Schema.String;
+    /**
+     * The `credentialRevision` the refusal was observed on. When the stored credential has moved on
+     * since, nothing is marked and the answer's `outcome` is `superseded`.
+     */
+    readonly revision: Schema.optional<Schema.Int>;
 }>;
 export type MarkConnectedAccountInvalidRequest = typeof markConnectedAccountInvalidRequestSchema.Type;
+export declare const markConnectedAccountInvalidResponseSchema: Schema.Struct<{
+    readonly connectedAccountId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly provider: Schema.Literals<readonly ["claude", "codex", "github"]>;
+    readonly name: Schema.String;
+    readonly kind: Schema.String;
+    readonly status: Schema.Literals<readonly ["active", "invalid", "archived"]>;
+    readonly metadata: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly connectedAt: Schema.String;
+    readonly updatedAt: Schema.String;
+    readonly lastUsedAt: Schema.NullOr<Schema.String>;
+    readonly lastSyncedAt: Schema.NullOr<Schema.String>;
+    /** Freshness as the control plane observed it; see the schema above for what null means. */
+    readonly credential: Schema.Struct<{
+        /** When the access token expires. Hours, for a Claude session credential. */
+        readonly accessExpiresAt: Schema.NullOr<Schema.String>;
+        /** When the grant itself expires, after which reconnecting is the only way back. */
+        readonly refreshExpiresAt: Schema.NullOr<Schema.String>;
+        /** When the platform last rotated or checked this credential. */
+        readonly lastRefreshAt: Schema.NullOr<Schema.String>;
+        /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
+        readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
+    }>;
+    /** Whether this is the owner's default for its provider. Absent from older control planes. */
+    readonly isDefault: Schema.optional<Schema.Boolean>;
+    /**
+     * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+     * stores different bytes. Absent from older control planes.
+     */
+    readonly credentialRevision: Schema.optional<Schema.Int>;
+    /** `marked`: the account is now invalid. `superseded`: a newer credential, left as it was. */
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["marked", "superseded"]>>;
+}>;
+export type MarkConnectedAccountInvalidResponse = typeof markConnectedAccountInvalidResponseSchema.Type;
+export declare const setConnectedAccountDefaultRequestSchema: Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+    readonly connectedAccountId: Schema.String;
+}>;
+export type SetConnectedAccountDefaultRequest = typeof setConnectedAccountDefaultRequestSchema.Type;
 declare const ConnectedAccountBadRequestError_base: Schema.Class<ConnectedAccountBadRequestError, Schema.TaggedStruct<"ConnectedAccountBadRequestError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -100,6 +169,14 @@ export declare class ConnectedAccountNotFoundError extends ConnectedAccountNotFo
 }
 declare const ConnectedAccountConflictError_base: Schema.Class<ConnectedAccountConflictError, Schema.TaggedStruct<"ConnectedAccountConflictError", {
     readonly message: Schema.String;
+    /**
+     * A stable reason, where one applies: `connected-account-ambiguous` (a connect without a target
+     * while the owner has several accounts for the provider), `connected-account-invalid` (a default
+     * chosen while its credential is invalid).
+     */
+    readonly code: Schema.optional<Schema.Literals<readonly ["connected-account-ambiguous", "connected-account-invalid"]>>;
+    /** The accounts a `connected-account-ambiguous` connect could have meant. */
+    readonly candidateAccountIds: Schema.optional<Schema.$Array<Schema.String>>;
 }>, import("effect/Cause").YieldableError>;
 export declare class ConnectedAccountConflictError extends ConnectedAccountConflictError_base {
 }
@@ -140,10 +217,28 @@ export declare const ConnectedAccountsGroup: HttpApiGroup.HttpApiGroup<"connecte
         /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
         readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
     }>;
+    /** Whether this is the owner's default for its provider. Absent from older control planes. */
+    readonly isDefault: Schema.optional<Schema.Boolean>;
+    /**
+     * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+     * stores different bytes. Absent from older control planes.
+     */
+    readonly credentialRevision: Schema.optional<Schema.Int>;
 }>>, Schema.toCodecJson<typeof ConnectedAccountNotFoundError | typeof ConnectedAccountInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"createConnectedAccount", "POST", "/", never, never, Schema.toCodecJson<Schema.Struct<{
     readonly ownerUserId: Schema.String;
     readonly provider: Schema.Literals<readonly ["claude", "codex", "github"]>;
+    /**
+     * The account to connect or replace by name; a new name is a new account, and `default` names
+     * the owner's chosen default. The owner's first account for the provider is named `default`
+     * whatever this says. With neither `name` nor `accountId` (or `default` while none is chosen),
+     * the owner's only account is replaced, and with several the connect is refused (`409`,
+     * `connected-account-ambiguous`, with `candidateAccountIds`).
+     */
     readonly name: Schema.optional<Schema.String>;
+    /** Replace this account (the owner's, of `provider`). Not with `name`. */
+    readonly accountId: Schema.optional<Schema.String>;
+    /** Make the connected account the owner's default for the provider, in the same write. */
+    readonly makeDefault: Schema.optional<Schema.Boolean>;
     readonly secret: Schema.String;
 }>>, never, Schema.toCodecJson<Schema.Struct<{
     readonly connectedAccountId: Schema.String;
@@ -168,6 +263,13 @@ export declare const ConnectedAccountsGroup: HttpApiGroup.HttpApiGroup<"connecte
         /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
         readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
     }>;
+    /** Whether this is the owner's default for its provider. Absent from older control planes. */
+    readonly isDefault: Schema.optional<Schema.Boolean>;
+    /**
+     * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+     * stores different bytes. Absent from older control planes.
+     */
+    readonly credentialRevision: Schema.optional<Schema.Int>;
 }>>, Schema.toCodecJson<typeof ConnectedAccountBadRequestError | typeof ConnectedAccountNotFoundError | typeof ConnectedAccountConflictError | typeof ConnectedAccountServiceUnavailableError | typeof ConnectedAccountInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listConnectedAccounts", "GET", "/", never, Schema.toCodecStringTree<Schema.Struct<{
     readonly ownerUserId: Schema.String;
 }>>, never, never, Schema.toCodecJson<Schema.Struct<{
@@ -194,11 +296,60 @@ export declare const ConnectedAccountsGroup: HttpApiGroup.HttpApiGroup<"connecte
             /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
             readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
         }>;
+        /** Whether this is the owner's default for its provider. Absent from older control planes. */
+        readonly isDefault: Schema.optional<Schema.Boolean>;
+        /**
+         * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+         * stores different bytes. Absent from older control planes.
+         */
+        readonly credentialRevision: Schema.optional<Schema.Int>;
     }>>;
 }>>, Schema.toCodecJson<typeof ConnectedAccountInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"markConnectedAccountInvalid", "POST", "/:connectedAccountId/mark-invalid", Schema.toCodecStringTree<Schema.Struct<{
     readonly connectedAccountId: Schema.String;
 }>>, never, Schema.toCodecJson<Schema.Struct<{
     readonly ownerUserId: Schema.String;
+    /**
+     * The `credentialRevision` the refusal was observed on. When the stored credential has moved on
+     * since, nothing is marked and the answer's `outcome` is `superseded`.
+     */
+    readonly revision: Schema.optional<Schema.Int>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly connectedAccountId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly provider: Schema.Literals<readonly ["claude", "codex", "github"]>;
+    readonly name: Schema.String;
+    readonly kind: Schema.String;
+    readonly status: Schema.Literals<readonly ["active", "invalid", "archived"]>;
+    readonly metadata: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly connectedAt: Schema.String;
+    readonly updatedAt: Schema.String;
+    readonly lastUsedAt: Schema.NullOr<Schema.String>;
+    readonly lastSyncedAt: Schema.NullOr<Schema.String>;
+    /** Freshness as the control plane observed it; see the schema above for what null means. */
+    readonly credential: Schema.Struct<{
+        /** When the access token expires. Hours, for a Claude session credential. */
+        readonly accessExpiresAt: Schema.NullOr<Schema.String>;
+        /** When the grant itself expires, after which reconnecting is the only way back. */
+        readonly refreshExpiresAt: Schema.NullOr<Schema.String>;
+        /** When the platform last rotated or checked this credential. */
+        readonly lastRefreshAt: Schema.NullOr<Schema.String>;
+        /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
+        readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
+    }>;
+    /** Whether this is the owner's default for its provider. Absent from older control planes. */
+    readonly isDefault: Schema.optional<Schema.Boolean>;
+    /**
+     * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+     * stores different bytes. Absent from older control planes.
+     */
+    readonly credentialRevision: Schema.optional<Schema.Int>;
+    /** `marked`: the account is now invalid. `superseded`: a newer credential, left as it was. */
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["marked", "superseded"]>>;
+}>>, Schema.toCodecJson<typeof ConnectedAccountNotFoundError | typeof ConnectedAccountInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"setConnectedAccountDefault", "PUT", "/defaults/:provider", Schema.toCodecStringTree<Schema.Struct<{
+    readonly provider: Schema.Literals<readonly ["claude", "codex", "github"]>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+    readonly connectedAccountId: Schema.String;
 }>>, never, Schema.toCodecJson<Schema.Struct<{
     readonly connectedAccountId: Schema.String;
     readonly ownerUserId: Schema.String;
@@ -222,5 +373,12 @@ export declare const ConnectedAccountsGroup: HttpApiGroup.HttpApiGroup<"connecte
         /** What that attempt did: `refreshed`, `fresh` (nothing to do), or `failed`. */
         readonly lastRefreshOutcome: Schema.NullOr<Schema.Literals<readonly ["refreshed", "fresh", "failed"]>>;
     }>;
-}>>, Schema.toCodecJson<typeof ConnectedAccountNotFoundError | typeof ConnectedAccountInternalServerError>, never, never>, false>;
+    /** Whether this is the owner's default for its provider. Absent from older control planes. */
+    readonly isDefault: Schema.optional<Schema.Boolean>;
+    /**
+     * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+     * stores different bytes. Absent from older control planes.
+     */
+    readonly credentialRevision: Schema.optional<Schema.Int>;
+}>>, Schema.toCodecJson<typeof ConnectedAccountNotFoundError | typeof ConnectedAccountConflictError | typeof ConnectedAccountInternalServerError>, never, never>, false>;
 export {};

package/dist/core-api/connected-accounts.js

@@ -12,6 +12,11 @@ provider-shaped plaintext INTO the API, where it is validated, encrypted (AES-25
 expose only non-secret metadata (token suffix, codex account id/email, github login+scopes).
 `markConnectedAccountInvalid` is the internal 401-feedback hook (worker/sync-back observed the
 provider rejecting the credential).
+
+Each person has at most one default account per provider, the one the selector `default` (the
+SDK's `true`) means. Connecting a person's first account for a provider makes it the default;
+after that only `makeDefault` on a connect, or `setConnectedAccountDefault`, changes it.
+Disconnecting the default leaves the person without one: no other account is chosen for them.
 */
 export const connectedAccountProviderSchema = Schema.Literals(["claude", "codex", "github"]);
 export const connectedAccountStatusSchema = Schema.Literals(["active", "invalid", "archived"]);
@@ -47,12 +52,29 @@ export const connectedAccountSummarySchema = Schema.Struct({
     lastSyncedAt: Schema.NullOr(Schema.String),
     /** Freshness as the control plane observed it; see the schema above for what null means. */
     credential: connectedAccountCredentialSchema,
+    /** Whether this is the owner's default for its provider. Absent from older control planes. */
+    isDefault: Schema.optional(Schema.Boolean),
+    /**
+     * Which credential the account holds: starts at 1 and moves on whenever a reconnect or refresh
+     * stores different bytes. Absent from older control planes.
+     */
+    credentialRevision: Schema.optional(Schema.Int),
 });
 export const createConnectedAccountRequestSchema = Schema.Struct({
     ownerUserId: NonEmptyString,
     provider: connectedAccountProviderSchema,
-    // Multiple accounts per provider are allowed; defaults to "default".
+    /**
+     * The account to connect or replace by name; a new name is a new account, and `default` names
+     * the owner's chosen default. The owner's first account for the provider is named `default`
+     * whatever this says. With neither `name` nor `accountId` (or `default` while none is chosen),
+     * the owner's only account is replaced, and with several the connect is refused (`409`,
+     * `connected-account-ambiguous`, with `candidateAccountIds`).
+     */
     name: Schema.optional(NonEmptyString),
+    /** Replace this account (the owner's, of `provider`). Not with `name`. */
+    accountId: Schema.optional(NonEmptyString),
+    /** Make the connected account the owner's default for the provider, in the same write. */
+    makeDefault: Schema.optional(Schema.Boolean),
     // Provider-shaped plaintext: claude setup-token or verbatim .credentials.json contents /
     // verbatim codex auth.json contents / github token. Encrypted server-side; never stored or
     // echoed back as-is. Not trimmed here — pasted credential files are stored verbatim.
@@ -66,6 +88,20 @@ export const listConnectedAccountsResponseSchema = Schema.Struct({
 });
 export const markConnectedAccountInvalidRequestSchema = Schema.Struct({
     ownerUserId: NonEmptyString,
+    /**
+     * The `credentialRevision` the refusal was observed on. When the stored credential has moved on
+     * since, nothing is marked and the answer's `outcome` is `superseded`.
+     */
+    revision: Schema.optional(Schema.Int),
+});
+export const markConnectedAccountInvalidResponseSchema = Schema.Struct({
+    ...connectedAccountSummarySchema.fields,
+    /** `marked`: the account is now invalid. `superseded`: a newer credential, left as it was. */
+    outcome: Schema.optional(Schema.Literals(["marked", "superseded"])),
+});
+export const setConnectedAccountDefaultRequestSchema = Schema.Struct({
+    ownerUserId: NonEmptyString,
+    connectedAccountId: NonEmptyString,
 });
 export class ConnectedAccountBadRequestError extends Schema.TaggedError()("ConnectedAccountBadRequestError", {
     message: Schema.String,
@@ -77,6 +113,14 @@ export class ConnectedAccountNotFoundError extends Schema.TaggedError()("Connect
 }
 export class ConnectedAccountConflictError extends Schema.TaggedError()("ConnectedAccountConflictError", {
     message: Schema.String,
+    /**
+     * A stable reason, where one applies: `connected-account-ambiguous` (a connect without a target
+     * while the owner has several accounts for the provider), `connected-account-invalid` (a default
+     * chosen while its credential is invalid).
+     */
+    code: Schema.optional(Schema.Literals(["connected-account-ambiguous", "connected-account-invalid"])),
+    /** The accounts a `connected-account-ambiguous` connect could have meant. */
+    candidateAccountIds: Schema.optional(Schema.Array(NonEmptyString)),
 }, { httpApiStatus: 409 }) {
 }
 export class ConnectedAccountServiceUnavailableError extends Schema.TaggedError()("ConnectedAccountServiceUnavailableError", {
@@ -88,11 +132,9 @@ export class ConnectedAccountInternalServerError extends Schema.TaggedError()("C
 }, { httpApiStatus: 500 }) {
 }
 const connectedAccountIdParams = Schema.Struct({ connectedAccountId: NonEmptyString });
+const connectedAccountProviderParams = Schema.Struct({ provider: connectedAccountProviderSchema });
 export const ConnectedAccountsGroup = HttpApiGroup.make("connectedAccounts")
-    .add(
-// Connect/replace: upserts on (owner, provider, name), so reconnecting swaps the sealed
-// payload in place instead of erroring.
-HttpApiEndpoint.post("createConnectedAccount", "/", {
+    .add(HttpApiEndpoint.post("createConnectedAccount", "/", {
     payload: createConnectedAccountRequestSchema,
     success: connectedAccountSummarySchema.pipe(HttpApiSchema.status(201)),
     error: [
@@ -122,7 +164,17 @@ HttpApiEndpoint.delete("archiveConnectedAccount", "/:connectedAccountId", {
 HttpApiEndpoint.post("markConnectedAccountInvalid", "/:connectedAccountId/mark-invalid", {
     params: connectedAccountIdParams,
     payload: markConnectedAccountInvalidRequestSchema,
-    success: connectedAccountSummarySchema,
+    success: markConnectedAccountInvalidResponseSchema,
     error: [ConnectedAccountNotFoundError, ConnectedAccountInternalServerError],
+}))
+    .add(HttpApiEndpoint.put("setConnectedAccountDefault", "/defaults/:provider", {
+    params: connectedAccountProviderParams,
+    payload: setConnectedAccountDefaultRequestSchema,
+    success: connectedAccountSummarySchema,
+    error: [
+        ConnectedAccountNotFoundError,
+        ConnectedAccountConflictError,
+        ConnectedAccountInternalServerError,
+    ],
 }))
     .annotate(OpenApi.Description, "Connected provider accounts (Claude / Codex / GitHub credentials). Secret material is never returned by any endpoint.");