@shipstatic/ship 3.4.0 → 3.5.0

package/dist/index.d.cts

@@ -511,8 +511,7 @@ interface DomainShareResponse {
  * the console sends a stuck reader to it rather than to the general docs. If
  * the spellings ever diverged, nothing would fail: the link would open the page
  * at its top and nobody would be told, the silent-drift class this
- * constitution exists to delete ({@link SIGN_IN_RETURN_PARAM} is the same shape
- * one domain over).
+ * constitution exists to delete.
  */
 declare const SETUP_TROUBLESHOOTING_ANCHOR = "troubleshooting";
 /**
@@ -717,13 +716,13 @@ declare const AccountPlan: {
 };
 type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
- * The three things an account ACCUMULATES, and therefore the three things a
+ * The four things an account ACCUMULATES, and therefore the four things a
  * plan caps. One word for the count and for the ceiling: `Account.usage` and
  * `Account.caps` are the same shape, so a surface renders "2 of 3" by
  * dividing one by the other and can never divide by a different denominator
  * than the 403 uses.
  *
- * All three are counts plans SELL, and every plan publishes a number for each.
+ * All four are counts plans SELL, and every plan publishes a number for each.
  * A platform domain (`my-app.shipstatic.com`) is among them: the namespace
  * is the platform's, so every plan bounds how many names one account may take
  * from it — which is not the address every deployment gets by construction
@@ -763,12 +762,81 @@ interface Caps {
      */
     readonly customDomains: number;
     /**
-     * Members of the account, the owner included: one membership row each, so
-     * a pending invitation is not yet a member. As `usage` it is how many the
-     * account has, as `caps` how many its plan allows.
+     * Member places. As `caps` it is how many people the plan allows in the
+     * account, the owner included. As `usage` it is the members the account
+     * has: one membership row each. A pending invitation holds a place too,
+     * counted beside it as {@link AccountUsage.invitations}, so what stands
+     * against this cap is {@link placesTaken}, members and invitations
+     * together.
      */
     readonly members: number;
 }
+/**
+ * What the account holds: every cap's count, and the pending invitations.
+ *
+ * A member place is taken by a member or by a pending invitation, and an
+ * account never holds more of the two together than its plan's `members`
+ * cap: the invite door refuses a new invitation when the places are taken,
+ * and a move down a tier is booked only when the places fit the destination.
+ * The count has no cap of its own, which is why it is a field of the usage
+ * and not of {@link Caps}: the place it takes is a member's.
+ *
+ * Only a member pauses, though. An account over its members cap pauses every
+ * member while it does not fit; a pending invitation pauses nobody and
+ * counts toward no pause.
+ */
+interface AccountUsage extends Caps {
+    /**
+     * Invitations still open: pending, and not yet expired. An expired one
+     * holds nothing, whether or not a sweep has removed its row.
+     */
+    readonly invitations: number;
+}
+/** The member places an account has taken: its members, and its pending invitations. */
+declare function placesTaken(usage: Pick<AccountUsage, 'members' | 'invitations'>): number;
+/**
+ * The kind each count of {@link AccountUsage} names, as a person reads it:
+ * one and many. The one vocabulary every surface that says a count uses, the
+ * api's cap refusals and the console's room notes alike, so "custom domain"
+ * is one word wherever it is met. A person reads "ShipStatic domain" where
+ * the code says platform domain; the code's word never reaches them.
+ */
+declare const USAGE_KIND: Record<keyof AccountUsage, {
+    readonly one: string;
+    readonly many: string;
+}>;
+/**
+ * What an account holds beyond a set of caps, per kind, only the kinds that
+ * are over: what a move down a tier must shed before it is booked, and what
+ * the console notes on a cheaper card.
+ *
+ * Member places are read against `caps.members`: the places over the cap are
+ * counted once ({@link placesTaken} less the cap), members are named first,
+ * because a member over the cap has to go whatever else the account holds,
+ * and what is over after them is the invitations to cancel. So two members
+ * and one invitation against a cap of one is one member and one invitation,
+ * and five members against the same cap is four members and no invitation.
+ * The two domain kinds are read against their own caps. Deployments are not
+ * read at all: nothing pauses them, and above their cap they only block
+ * creation (see {@link Caps}).
+ */
+declare function excessOver(usage: AccountUsage, caps: Caps): Partial<AccountUsage>;
+/**
+ * Counts of kinds in words, people first: "4 members and 2 custom domains",
+ * or nothing. The order is {@link USAGE_KIND}'s minus the two kinds a count never
+ * names here, deployments and invitations, which have their own sentence
+ * ({@link fitPhrase}).
+ */
+declare function countPhrase(excess: Partial<AccountUsage>): string;
+/**
+ * What to do before an account fits a set of caps, in words: "remove 1
+ * member and cancel 1 invitation", "remove 2 custom domains", "cancel 2
+ * invitations", or nothing when it fits. Two verbs, because a member place is
+ * freed two ways: a member is removed, a pending invitation is cancelled. The
+ * api's change door and the console's room notes say this one phrase, so a
+ * refusal and the note that preceded it cannot differ.
+ */
+declare function fitPhrase(excess: Partial<AccountUsage>): string;
 /**
  * A person's standing in an account. `owner` founded it and alone manages
  * billing, credentials, members and deletion; `member` uses its resources
@@ -836,13 +904,17 @@ interface Account {
      * still work, every write is refused. The plan is unchanged underneath.
      */
     readonly suspended: boolean;
-    /** What the account currently holds — see {@link Caps}. */
-    readonly usage: Caps;
     /**
-     * What the account is allowed to hold, under the same keys as
-     * {@link usage}, so the pair divides. These are the account's EFFECTIVE
-     * caps: its plan's numbers, plus whatever the operator granted it
-     * individually.
+     * What the account currently holds: every cap's count, and the pending
+     * invitations beside them — see {@link AccountUsage}.
+     */
+    readonly usage: AccountUsage;
+    /**
+     * What the account is allowed to hold, under {@link usage}'s cap keys, so
+     * the pair divides. These are the account's EFFECTIVE caps: its plan's
+     * numbers, plus whatever the operator granted it individually. The one key
+     * of `usage` absent here is `invitations`, which has no cap of its own: a
+     * pending invitation takes a member place, so it counts against `members`.
      */
     readonly caps: Caps;
     /**
@@ -862,15 +934,16 @@ interface Account {
      */
     readonly access?: AccountAccess;
     /**
-     * Whether the account's MEMBERS are admitted today: `paused` while it holds
-     * more members than its plan allows, until the owner upgrades or removes
-     * members. It is {@link access} for everyone who is not the owner, published
-     * for the account so the one person it never pauses can be told; the API
-     * derives both from one rule, so a console reads the pause here rather than
-     * re-deriving it from the member counts. Optional by the additive-evolution
-     * law: a response that predates it is `active`.
+     * The account's own standing, beside the credential's ({@link access}):
+     * whether its MEMBERS are admitted today, `paused` while it holds more
+     * members than its plan allows, until the owner upgrades or removes
+     * members. It is {@link access} for everyone who is not the owner,
+     * published for the account so the one person it never pauses can be told;
+     * the API derives both from one rule, so a console reads the pause here
+     * rather than re-deriving it from the member counts. Optional by the
+     * additive-evolution law: a response that predates it is `active`.
      */
-    readonly members?: AccountAccess;
+    readonly membership?: AccountAccess;
     /** Unix timestamp (seconds) when account was created */
     readonly created: number;
     /** Unix timestamp (seconds) when account was activated (first deployment), null if not yet activated */
@@ -1613,20 +1686,6 @@ interface PingResponse {
  * already share the credential prefixes below.
  */
 declare const AUTH_BASE_PATH = "/auth";
-/**
- * The query marker a completed sign-in LANDS with.
- *
- * The API's magic-link verify leg stamps `?signing-in=1` onto its success
- * redirect, and the console boots into its wait screen on seeing it — two
- * repos, one spelling, which is why it lives here. Success is marked and the
- * error leg deliberately is NOT: the console gives the marker precedence, so
- * a marked error would render a wait that resolves to bare doors with the
- * error's sentence lost. If the spellings ever diverged the failure would be
- * invisible to every suite — email landings would flash the doors for one
- * round trip instead of waiting — which is exactly the silent-drift class
- * this constitution exists to delete.
- */
-declare const SIGN_IN_RETURN_PARAM = "signing-in";
 /**
  * How a request (or recorded activity) was authorized.
  *
@@ -2049,6 +2108,9 @@ declare const SECTIONS: {
     readonly settings: {
         readonly owner: false;
     };
+    readonly claim: {
+        readonly owner: false;
+    };
     readonly upgrade: {
         readonly owner: true;
     };
@@ -2061,6 +2123,10 @@ declare const SECTIONS: {
 };
 /** A section's first segment. */
 type ConsoleSection = keyof typeof SECTIONS;
+/** The pages that exist before an account is known, by first segment. */
+declare const DOOR_SEGMENTS: readonly ["login", "register", "logout", "invitation", "consent"];
+/** A door's first segment. */
+type DoorSegment = (typeof DOOR_SEGMENTS)[number];
 /** The two fragments of the settings page a link may name. */
 type SettingsFragment = 'members' | 'api-key';
 /**
@@ -2094,6 +2160,8 @@ declare function consolePaths(account?: string): {
         deployment: (domain: string) => string;
     };
     settings: (fragment?: SettingsFragment) => string;
+    /** The claim of an anonymous deployment into this account; the API mails the bare form. */
+    claim: (code: string) => string;
     /** Settings, marked as the landing of a Stripe Customer Portal return. */
     settingsAfterBilling: () => string;
     upgrade: (plan?: AccountPlanType) => string;
@@ -2104,13 +2172,31 @@ declare function consolePaths(account?: string): {
 };
 /** The builders `consolePaths` returns. */
 type ConsolePaths = ReturnType<typeof consolePaths>;
-/** The doors: the pages that exist before an account is known. */
+/** Where a sign-in door's journey goes on: the console path a `?next` carries. */
+interface Journey {
+    readonly next?: string;
+}
+/**
+ * The doors: the pages a PERSON stands on before an account is known, one
+ * builder per door segment and named for it: signing in and out, joining an
+ * account, granting an app access. A door's object rides its path (the
+ * sign-in link's token, the invitation's id), and the journey rides the
+ * query, so the three doors a sign-in moves through take it by name. What a
+ * person does IN an account is a section (`consolePaths`), the claim among
+ * them.
+ *
+ * ```ts
+ * doors.login({ token, next: '/claim/abc' })
+ * // '/login/<token>?next=%2Fclaim%2Fabc'
+ * ```
+ */
 declare const doors: {
-    readonly login: (next?: string) => string;
-    readonly register: (next?: string) => string;
-    readonly logout: () => string;
+    readonly login: ({ token, next }?: Journey & {
+        readonly token?: string;
+    }) => string;
+    readonly register: ({ next }?: Journey) => string;
+    readonly logout: ({ next }?: Journey) => string;
     readonly invitation: (invitation: string) => string;
-    readonly claim: (code: string) => string;
     readonly consent: () => string;
 };
 /**
@@ -2125,10 +2211,21 @@ declare function billingReturnOf(search: string): BillingReturn | null;
  * the account exists is the server's answer, never the path's.
  */
 declare function accountOfPath(path: string): string | null;
-/** Whether a path names a claim link (`/claim/:code`, a bearer credential). */
+/**
+ * The door a path names, or null for an account place or the operator
+ * partition. Every question about doors reads this one answer: which page is
+ * an auth page, which errand a destination carries, what a vendor must not
+ * see. `/login/<token>` is the login door, as `/invitation/<id>` is the
+ * invitation door: a door's object is the rest of its path.
+ */
+declare function doorOf(path: string): DoorSegment | null;
+/**
+ * Whether a path names the claim section, in either form: `/claim/:code`, and
+ * the same under `/<account>/`. The code is a bearer credential, which is why
+ * a reader asks about this section by name: the doors title their visitor by
+ * it, and analytics elides it.
+ */
 declare const isClaimPath: (path: string) => boolean;
-/** Whether a path names an invitation (`/invitations/:invitation`). */
-declare const isInvitationPath: (path: string) => boolean;
 /**
  * Whether a path names the upgrade section, in either form: `/upgrade`,
  * `/upgrade/:plan`, and the same under `/<account>/`.
@@ -2461,20 +2558,6 @@ interface Plan {
      * nothing (a plan sold by conversation publishes no numbers).
      */
     readonly caps: Caps | null;
-    /**
-     * Why this row cannot be ordered right now — the closed door's own sentence,
-     * verbatim — or absent when the way is open. A menu lists what can be
-     * ordered, and a row that is sold but not yet orderable (its door is closed:
-     * checkout unbuilt, a feature unfinished) SAYS SO on the menu instead of
-     * only at the order.
-     *
-     * Clients branch on PRESENCE and render the sentence unchanged — they know
-     * *that* the row is closed, never *which* door or *when it lifts*; the
-     * vocabulary of doors stays server-side. The same rule the refusal follows:
-     * `POST /billing/change` onto a closed row answers 400 with
-     * `details.closed`, and its `message` is this sentence.
-     */
-    readonly closed?: string;
 }
 /**
  * Response for `GET /plans` — the whole public menu, in display order.
@@ -2512,17 +2595,18 @@ interface PlanChangeRequest {
 }
 /**
  * `details` of the change door's refusal of a move down a tier the account
- * does not fit: the account holds more members, custom domains or platform
- * domains than the destination allows.
+ * does not fit: the account holds more members, pending invitations, custom
+ * domains or platform domains than the destination allows.
  *
  * `excess` counts what to REMOVE before asking again, per kind, keyed like
- * {@link Caps}; only the kinds over the destination's caps appear. The
- * door's `message` names the same counts in a sentence, and that sentence is
- * what a surface shows; the counts are for a client that acts on the
- * refusal.
+ * {@link AccountUsage}; only the kinds over the destination's caps appear
+ * ({@link excessOver}). Members and invitations are counted apart, since one
+ * is removed and the other cancelled. The door's `message` names the same
+ * counts in a sentence, and that sentence is what a surface shows; the
+ * counts are for a client that acts on the refusal.
  */
 interface PlanChangeRefusalDetails {
-    readonly excess: Partial<Caps>;
+    readonly excess: Partial<AccountUsage>;
 }
 /**
  * The pending plan change — a Stripe Subscription Schedule, mirrored onto the
@@ -3855,6 +3939,6 @@ declare class Ship extends Ship$1 {
 }
 
 declare namespace Ship {
-  export { ACCOUNT_HEADER, API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountAccess, AccountDeleteResponse, AccountKeyResponse, AccountPlan, AccountPlanType, AccountRefusal, AccountRefusalType, AccountResource, AccountRole, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BUILD_SETTINGS, BillingInterval, BillingPortalSession, BillingSyncResponse, BuildFailureDetails, CALLER, Caps, ConsoleErrand, ConsolePaths, ConsoleSection, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_FILE_GRAMMAR, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployFileEncoding, DeployFileSpec, DeployInput, DeployTransport, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerification, DomainVerificationType, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, Plan, PlanChangeRefusalDetails, PlanChangeRequest, PlanChangeResponse, PlanDestination, PlansResponse, PlatformLimitKey, PlatformLimits, RequestResult, ResourceContext, SECTIONS, SETUP_TROUBLESHOOTING_ANCHOR, SHIP_ENV, SHIP_VIA_ENV, SIGN_IN_RETURN_PARAM, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, ScheduledChange, SettingsFragment, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, USER_VISIBLE_EVENTS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, doors, errandOf, extractSubdomain, filterJunk, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isInvitationPath, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };
+  export { ACCOUNT_HEADER, API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountAccess, AccountDeleteResponse, AccountKeyResponse, AccountPlan, AccountPlanType, AccountRefusal, AccountRefusalType, AccountResource, AccountRole, AccountUsage, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BUILD_SETTINGS, BillingInterval, BillingPortalSession, BillingSyncResponse, BuildFailureDetails, CALLER, Caps, ConsoleErrand, ConsolePaths, ConsoleSection, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_FILE_GRAMMAR, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployFileEncoding, DeployFileSpec, DeployInput, DeployTransport, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerification, DomainVerificationType, DomainVerifyResponse, DoorSegment, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, Plan, PlanChangeRefusalDetails, PlanChangeRequest, PlanChangeResponse, PlanDestination, PlansResponse, PlatformLimitKey, PlatformLimits, RequestResult, ResourceContext, SECTIONS, SETUP_TROUBLESHOOTING_ANCHOR, SHIP_ENV, SHIP_VIA_ENV, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, ScheduledChange, SettingsFragment, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, USAGE_KIND, USER_VISIBLE_EVENTS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, countPhrase, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, doorOf, doors, errandOf, excessOver, extractSubdomain, filterJunk, fitPhrase, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, placesTaken, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };
 }
 export = Ship;