@riverbankcms/sdk 0.130.0 → 0.132.0

package/dist/_dts/core/src/booking-vertical-config.d.ts

@@ -0,0 +1,66 @@
+import type { VerticalBookingPresetDefinition, VerticalDefinition, VerticalId, VerticalPresetId } from './booking-verticals';
+export type NonEmptyVerticalPresetIds = readonly [
+    VerticalPresetId,
+    ...VerticalPresetId[]
+];
+export type UnconfiguredSiteVerticalBookingConfig = Readonly<{
+    verticalId: null;
+    selectedPresetIds: readonly [];
+}>;
+export type ConfiguredSiteVerticalBookingConfig = Readonly<{
+    verticalId: VerticalId;
+    selectedPresetIds: NonEmptyVerticalPresetIds;
+}>;
+export type SiteVerticalBookingConfig = UnconfiguredSiteVerticalBookingConfig | ConfiguredSiteVerticalBookingConfig;
+export type ParsedSiteVerticalBookingConfig = Readonly<{
+    verticalId: VerticalId | null;
+    selectedPresetIds: readonly VerticalPresetId[];
+}>;
+export type RawSiteVerticalBookingConfig = Readonly<{
+    verticalId?: unknown;
+    selectedPresetIds?: unknown;
+}>;
+export type SiteVerticalConfigIssue = Readonly<{
+    code: 'unknown_vertical';
+    rawValue: unknown;
+}> | Readonly<{
+    code: 'missing_vertical';
+}> | Readonly<{
+    code: 'unknown_preset';
+    rawValue: unknown;
+}> | Readonly<{
+    code: 'empty_selected_presets';
+}> | Readonly<{
+    code: 'preset_vertical_mismatch';
+}> | Readonly<{
+    code: 'duplicate_preset_id';
+}> | Readonly<{
+    code: 'duplicate_canonical_behaviour';
+}> | Readonly<{
+    code: 'future_preset_selected';
+}>;
+export type ResolvedSiteVerticalBookingConfig = Readonly<{
+    kind: 'unconfigured';
+    config: SiteVerticalBookingConfig;
+}> | Readonly<{
+    kind: 'configured';
+    config: ConfiguredSiteVerticalBookingConfig;
+    selectedPresets: readonly VerticalBookingPresetDefinition[];
+}> | Readonly<{
+    kind: 'invalid';
+    config: ParsedSiteVerticalBookingConfig;
+    issues: readonly SiteVerticalConfigIssue[];
+}>;
+export declare function parseVerticalId(value: unknown): VerticalId | null;
+export declare function parseVerticalPresetId(value: unknown): VerticalPresetId | null;
+export declare function getVerticalDefinition(verticalId: VerticalId): VerticalDefinition;
+export declare function getVerticalPresetDefinition(presetId: VerticalPresetId): VerticalBookingPresetDefinition;
+export declare function getDefaultOnboardingPresetForVertical(verticalId: VerticalId): VerticalBookingPresetDefinition | null;
+/**
+ * Construct a configured booking selection only when the supplied preset IDs
+ * form a valid selection for the vertical. Invalid, cross-vertical, future,
+ * duplicate, or empty selections return null.
+ */
+export declare function createSiteVerticalBookingConfig(verticalId: VerticalId, selectedPresetIds: readonly VerticalPresetId[]): ConfiguredSiteVerticalBookingConfig | null;
+export declare const DEFAULT_SITE_VERTICAL_BOOKING_CONFIG: SiteVerticalBookingConfig;
+export declare function resolveSiteVerticalBookingConfig(rawConfig: RawSiteVerticalBookingConfig | null | undefined): ResolvedSiteVerticalBookingConfig;

package/dist/_dts/core/src/booking-vertical-definitions.d.ts

@@ -0,0 +1,68 @@
+export type VerticalDefinition = Readonly<{
+    id: string;
+    label: string;
+    description: string;
+}>;
+export declare const VERTICAL_DEFINITIONS: readonly [{
+    readonly id: "yoga_wellness";
+    readonly label: "Yoga, meditation or mindfulness";
+    readonly description: "Yoga studios, wellness teachers, and movement practitioners.";
+}, {
+    readonly id: "fitness_pt";
+    readonly label: "Fitness and personal training";
+    readonly description: "Personal trainers, group training, and fitness programmes.";
+}, {
+    readonly id: "dance_school";
+    readonly label: "Dance school";
+    readonly description: "Dance classes, courses or terms, workshops, private lessons, and shows.";
+}, {
+    readonly id: "physiotherapy_physical_health";
+    readonly label: "Physiotherapy & physical health";
+    readonly description: "Physiotherapists, chiropractors, osteopaths, sports therapists, and rehabilitation practitioners.";
+}, {
+    readonly id: "massage_bodywork";
+    readonly label: "Massage & bodywork";
+    readonly description: "Massage therapists, bodyworkers, and somatic practitioners.";
+}, {
+    readonly id: "therapist_practitioner";
+    readonly label: "Therapist or practitioner";
+    readonly description: "Appointments, sessions, consultations, and occasional group work.";
+}, {
+    readonly id: "beauty_spa";
+    readonly label: "Beauty or spa";
+    readonly description: "Treatment-led businesses with optional workshops.";
+}, {
+    readonly id: "consultant_coach";
+    readonly label: "Consultant or coach";
+    readonly description: "One-to-one calls, workshops, courses, and retreats.";
+}, {
+    readonly id: "training_provider";
+    readonly label: "Training provider";
+    readonly description: "Courses, workshops, classes, appointments, and residential training.";
+}, {
+    readonly id: "retreat_centre";
+    readonly label: "Retreat centre";
+    readonly description: "Residential retreats, workshops, classes, courses, and private sessions.";
+}, {
+    readonly id: "music_school";
+    readonly label: "Music teacher or school";
+    readonly description: "Lessons, classes, terms, workshops, and performances.";
+}, {
+    readonly id: "voice_singing";
+    readonly label: "Voice & Singing";
+    readonly description: "Singing lessons, choirs, voice circles, workshops, and performances.";
+}, {
+    readonly id: "performing_arts_school";
+    readonly label: "Theatre or performing arts school";
+    readonly description: "Classes, terms, workshops, performances, and lessons.";
+}, {
+    readonly id: "community_wellbeing";
+    readonly label: "Community or wellbeing centre";
+    readonly description: "Groups, workshops, courses, appointments, and retreats.";
+}, {
+    readonly id: "venue_event_space";
+    readonly label: "Venue or event space";
+    readonly description: "Room, resource, or access bookings. Depends on the future capacity-booking domain.";
+}];
+export type VerticalId = (typeof VERTICAL_DEFINITIONS)[number]['id'];
+export declare const VERTICAL_IDS: readonly VerticalId[];

package/dist/_dts/{api/src/bookingVerticalPreset.d.ts → core/src/booking-vertical-preset.d.ts}

@@ -1,4 +1,4 @@
-import type { CanonicalBookingBehaviour, VerticalBookingPreset, VerticalId, VerticalPresetAvailability } from './bookingVerticals';
+import type { CanonicalBookingBehaviour, VerticalBookingPreset, VerticalId, VerticalPresetAvailability } from './booking-verticals';
 export declare const BOOKING_ENGINE_BY_BEHAVIOUR: {
     readonly class: "event_series";
     readonly workshop: "event_series";

package/dist/_dts/core/src/booking-verticals.d.ts

@@ -0,0 +1,98 @@
+import { type EventPresetOverride } from './event-series-behaviour';
+import { BOOKING_DEFAULTS_BY_BEHAVIOUR, BOOKING_ENGINE_BY_BEHAVIOUR, VERTICAL_BOOKING_PRESETS } from './booking-vertical-catalog';
+import { VERTICAL_DEFINITIONS, VERTICAL_IDS } from './booking-vertical-definitions';
+import type { VerticalId } from './booking-vertical-definitions';
+import { DEFAULT_SITE_VERTICAL_BOOKING_CONFIG, createSiteVerticalBookingConfig, getDefaultOnboardingPresetForVertical, getVerticalDefinition, getVerticalPresetDefinition, parseVerticalId, parseVerticalPresetId, resolveSiteVerticalBookingConfig } from './booking-vertical-config';
+import type { ConfiguredSiteVerticalBookingConfig, NonEmptyVerticalPresetIds, ParsedSiteVerticalBookingConfig, RawSiteVerticalBookingConfig, ResolvedSiteVerticalBookingConfig, SiteVerticalBookingConfig, SiteVerticalConfigIssue, UnconfiguredSiteVerticalBookingConfig } from './booking-vertical-config';
+export type { VerticalId } from './booking-vertical-definitions';
+export { BOOKING_DEFAULTS_BY_BEHAVIOUR, BOOKING_ENGINE_BY_BEHAVIOUR, DEFAULT_SITE_VERTICAL_BOOKING_CONFIG, createSiteVerticalBookingConfig, getDefaultOnboardingPresetForVertical, getVerticalDefinition, getVerticalPresetDefinition, parseVerticalId, parseVerticalPresetId, resolveSiteVerticalBookingConfig, VERTICAL_BOOKING_PRESETS, VERTICAL_DEFINITIONS, VERTICAL_IDS, };
+export type { ConfiguredSiteVerticalBookingConfig, NonEmptyVerticalPresetIds, ParsedSiteVerticalBookingConfig, RawSiteVerticalBookingConfig, ResolvedSiteVerticalBookingConfig, SiteVerticalBookingConfig, SiteVerticalConfigIssue, UnconfiguredSiteVerticalBookingConfig, };
+export type VerticalBookingPresetDefinition = (typeof VERTICAL_BOOKING_PRESETS)[number];
+export type VerticalPresetId = VerticalBookingPresetDefinition['id'];
+export declare const CANONICAL_BOOKING_BEHAVIOURS: readonly ["class", "workshop", "course", "retreat", "performance", "appointment"];
+export type CanonicalBookingBehaviour = (typeof CANONICAL_BOOKING_BEHAVIOURS)[number];
+export declare const BOOKING_ENGINES: readonly ["event_series", "appointment_service"];
+export type BookingEngine = (typeof BOOKING_ENGINES)[number];
+export declare const VERTICAL_PRESET_AVAILABILITIES: readonly ["onboarding", "settings", "future"];
+export type VerticalPresetAvailability = (typeof VERTICAL_PRESET_AVAILABILITIES)[number];
+export type EventSeriesCanonicalBehaviour = Extract<CanonicalBookingBehaviour, 'class' | 'course' | 'workshop' | 'retreat' | 'performance'>;
+export type EventSeriesVerticalPresetId = Extract<VerticalPresetId, `${string}.${string}`>;
+export type EventSeriesVerticalPresetDefinition = VerticalBookingPresetDefinition & {
+    canonicalBehaviour: EventSeriesCanonicalBehaviour;
+};
+type BookingPassMembershipDefault = 'on' | 'off' | 'strict';
+export type BookingBehaviourDefaults = Readonly<{
+    passes: BookingPassMembershipDefault;
+    memberships: BookingPassMembershipDefault;
+}>;
+export type VerticalBookingPreset = Readonly<{
+    id: string;
+    verticalId: VerticalId;
+    canonicalBehaviour: CanonicalBookingBehaviour;
+    eventPresetOverride?: EventPresetOverride;
+    engine: BookingEngine;
+    availability: VerticalPresetAvailability;
+    label: string;
+    pluralLabel: string;
+    description: string;
+}>;
+export type VerticalDefinition = (typeof VERTICAL_DEFINITIONS)[number];
+export type EventSeriesVerticalPresetValidationError = 'unknown_vertical_preset' | 'non_event_series_preset' | 'canonical_behaviour_mismatch';
+export type EventSeriesVerticalPresetValidationResult = Readonly<{
+    ok: true;
+    preset: EventSeriesVerticalPresetDefinition;
+}> | Readonly<{
+    ok: false;
+    error: EventSeriesVerticalPresetValidationError;
+}>;
+export type VerticalPresetSelectionDisabledReason = 'last_selected_preset';
+export type VerticalPresetSelectionOption = Readonly<{
+    preset: VerticalBookingPresetDefinition;
+    checked: boolean;
+    disabledReason: VerticalPresetSelectionDisabledReason | null;
+}>;
+export type VerticalPresetSelectionUpdateError = 'unconfigured' | 'cross_vertical_preset' | 'future_preset' | 'last_selected_preset';
+export type VerticalPresetSelectionUpdateResult = Readonly<{
+    ok: true;
+    config: SiteVerticalBookingConfig;
+}> | Readonly<{
+    ok: false;
+    error: VerticalPresetSelectionUpdateError;
+    config: SiteVerticalBookingConfig;
+}>;
+export type CanonicalConfiguredSiteVerticalBookingConfigResult = Readonly<{
+    ok: true;
+    config: ConfiguredSiteVerticalBookingConfig;
+}> | Readonly<{
+    ok: false;
+    issues: readonly SiteVerticalConfigIssue[];
+}>;
+export declare function getVerticalPresetsForVertical(verticalId: VerticalId, options?: Readonly<{
+    availability?: VerticalPresetAvailability | 'selectable';
+}>): readonly VerticalBookingPresetDefinition[];
+export declare function getOnboardingPresetsForVertical(verticalId: VerticalId): readonly VerticalBookingPresetDefinition[];
+export declare function isEventSeriesCanonicalBehaviour(behaviour: CanonicalBookingBehaviour): behaviour is EventSeriesCanonicalBehaviour;
+export declare function isEventSeriesVerticalPresetDefinition(presetDefinition: VerticalBookingPresetDefinition): presetDefinition is EventSeriesVerticalPresetDefinition;
+export declare function validateEventSeriesVerticalPreset(input: Readonly<{
+    canonicalPreset: EventSeriesCanonicalBehaviour | 'term';
+    verticalPresetId: string | null | undefined;
+}>): EventSeriesVerticalPresetValidationResult;
+export declare function getSelectedCanonicalBehaviours(presetIds: readonly VerticalPresetId[]): readonly CanonicalBookingBehaviour[];
+export declare function getSelectedPresetForBehaviour(input: Readonly<{
+    presetIds: readonly VerticalPresetId[];
+    canonicalBehaviour: CanonicalBookingBehaviour;
+}>): VerticalBookingPresetDefinition | null;
+export declare function getVerticalPresetSelectionOptions(config: SiteVerticalBookingConfig | null | undefined): readonly VerticalPresetSelectionOption[];
+export declare function setVerticalPresetSelected(config: SiteVerticalBookingConfig | null | undefined, presetId: VerticalPresetId, selected: boolean): VerticalPresetSelectionUpdateResult;
+export declare function setVerticalPresetsSelected(config: SiteVerticalBookingConfig | null | undefined, presetIds: readonly VerticalPresetId[]): VerticalPresetSelectionUpdateResult;
+/**
+ * Return a configured selection in the catalog's canonical order.
+ *
+ * This deliberately delegates ordering and selection semantics to the core
+ * authority instead of making dashboard planners maintain a second catalog
+ * ordering implementation.  Runtime-invalid values are reported as a closed
+ * result so this pure helper never throws while planning.
+ */
+export declare function canonicalizeConfiguredBookingVerticalConfig(config: ConfiguredSiteVerticalBookingConfig): CanonicalConfiguredSiteVerticalBookingConfigResult;
+/** Compare configured booking selections by catalog order, not authored array order. */
+export declare function areConfiguredBookingVerticalConfigsEqual(left: ConfiguredSiteVerticalBookingConfig, right: ConfiguredSiteVerticalBookingConfig): boolean;

package/dist/_dts/core/src/branded.d.ts

@@ -24,6 +24,8 @@ export type BrandedIdParseError = {
 export declare function expectParsedBrandedId<TBrand>(result: Result<TBrand, BrandedIdParseError>): TBrand;
 export type EventInstanceId = Brand<string, 'EventInstanceId'>;
 export type SiteId = Brand<string, 'SiteId'>;
+/** An API key identifier, independent of the credential family it represents. */
+export type ApiKeyId = Brand<string, 'ApiKeyId'>;
 export type SiteRouteId = Brand<string, 'SiteRouteId'>;
 export type PageId = Brand<string, 'PageId'>;
 export type PageSurfaceId = Brand<string, 'PageSurfaceId'>;
@@ -159,6 +161,7 @@ export declare const unsafeAsEntryId: (id: string) => EntryId;
 export declare const unsafeAsPreviewEntryId: (id: string) => PreviewEntryId;
 export declare const unsafeAsEventInstanceId: (id: string) => EventInstanceId;
 export declare const unsafeAsSiteId: (id: string) => SiteId;
+export declare const unsafeAsApiKeyId: (id: string) => ApiKeyId;
 export declare const unsafeAsSiteRouteId: (id: string) => SiteRouteId;
 export declare const unsafeAsPageId: (id: string) => PageId;
 export declare const unsafeAsPageSurfaceId: (id: string) => PageSurfaceId;
@@ -268,6 +271,7 @@ export declare const unsafeAsEncounterRecordId: (id: string) => EncounterRecordI
 export declare const unsafeAsRecordEntryId: (id: string) => RecordEntryId;
 export declare const unsafeAsProtectedPayloadKeyVersion: (id: string) => ProtectedPayloadKeyVersion;
 export declare const parseSiteId: (value: unknown) => Result<SiteId, BrandedIdParseError>;
+export declare const parseApiKeyId: (value: unknown) => Result<ApiKeyId, BrandedIdParseError>;
 export declare const parseSiteRouteId: (value: unknown) => Result<SiteRouteId, BrandedIdParseError>;
 export declare const parsePageId: (value: unknown) => Result<PageId, BrandedIdParseError>;
 export declare const parsePageSurfaceId: (value: unknown) => Result<PageSurfaceId, BrandedIdParseError>;

package/dist/_dts/core/src/event-page-selection.d.ts

@@ -0,0 +1,22 @@
+/** Render-time selection beneath a canonical Event page. */
+export type EventOccurrenceContextData = Readonly<{
+    id: string;
+    seriesId: string;
+    startsAt: string;
+    endsAt: string;
+    timeZone: string;
+    capacityOverride?: number | null;
+    overrides?: Record<string, unknown> | null;
+}>;
+export type EventRunContextData = Readonly<{
+    seriesId: string;
+    identifier: string;
+    name: string | null;
+}>;
+export type EventPageSubrouteContext = Readonly<{
+    kind: 'event-occurrence';
+    occurrence: EventOccurrenceContextData;
+}> | Readonly<{
+    kind: 'event-run';
+    run: EventRunContextData;
+}>;

package/dist/_dts/core/src/event-page-surface-subject.d.ts

@@ -14,16 +14,33 @@ export type EventPageSurfaceSubjectRefWire = Readonly<{
     kind: 'eventOffering';
     eventOfferingId: string;
 }>;
-export type EventPageSurfaceSubject = Extract<EventPageSurfaceSubjectRef, {
+export type EventPageSurfaceBookingScope = 'single_occurrence' | 'whole_series';
+export type EventSeriesPageSurfaceSubject = Readonly<{
     kind: 'eventSeries';
+    eventSeriesId: EventSeriesId;
+    bookingScope: 'single_occurrence';
+}> | Readonly<{
+    kind: 'eventSeries';
+    eventSeriesId: EventSeriesId;
+    bookingScope: 'whole_series';
+    isWholeSeriesBooking: true;
+}>;
+export type EventSeriesPageSurfaceSubjectWire = Readonly<{
+    kind: 'eventSeries';
+    eventSeriesId: string;
+    bookingScope: 'single_occurrence';
 }> | Readonly<{
+    kind: 'eventSeries';
+    eventSeriesId: string;
+    bookingScope: 'whole_series';
+    isWholeSeriesBooking: true;
+}>;
+export type EventPageSurfaceSubject = EventSeriesPageSurfaceSubject | Readonly<{
     kind: 'eventOffering';
     eventOfferingId: EventOfferingId;
     availableEventSeriesIds: readonly EventSeriesId[];
 }>;
-export type EventPageSurfaceSubjectWire = Extract<EventPageSurfaceSubjectRefWire, {
-    kind: 'eventSeries';
-}> | Readonly<{
+export type EventPageSurfaceSubjectWire = EventSeriesPageSurfaceSubjectWire | Readonly<{
     kind: 'eventOffering';
     eventOfferingId: string;
     availableEventSeriesIds: readonly string[];
@@ -36,9 +53,13 @@ export type EventPageSurfaceSubjectParseError = Readonly<{
 }> | Readonly<{
     kind: 'invalidEventSeriesId';
     error: BrandedIdParseError;
+}> | Readonly<{
+    kind: 'invalidEventSeriesBookingScope';
+    bookingScope: unknown;
 }> | Readonly<{
     kind: 'invalidEventOfferingId';
     error: BrandedIdParseError;
 }>;
+export declare function createEventSeriesPageSurfaceSubject(eventSeriesId: EventSeriesId, bookingScope: EventPageSurfaceBookingScope): EventSeriesPageSurfaceSubject;
 export declare function parseEventPageSurfaceSubject(value: unknown): Result<EventPageSurfaceSubject, EventPageSurfaceSubjectParseError>;
 export declare function toEventPageSurfaceSubjectWire(subject: EventPageSurfaceSubject): EventPageSurfaceSubjectWire;

package/dist/_dts/core/src/event-pricing.d.ts

@@ -18,6 +18,11 @@ export type PublicCoursePriceDisplay = Readonly<{
     minAmount: number;
     maxAmount: number;
     currency: string;
+}> | Readonly<{
+    kind: "mixed";
+    paidFromAmount: number;
+    paidToAmount: number;
+    currency: string;
 }> | Readonly<{
     kind: "unavailable";
     currency: string;

package/dist/_dts/core/src/event-series-behaviour.d.ts

@@ -0,0 +1,16 @@
+export declare const EVENT_PRESET_VALUES: readonly ["event", "class", "course", "term", "workshop", "retreat", "performance"];
+export type EventPreset = (typeof EVENT_PRESET_VALUES)[number];
+export type EventPresetOverride = Extract<EventPreset, 'term'>;
+export type WholeSeriesEventPreset = Extract<EventPreset, 'course' | 'term'>;
+export type OrdinaryEventPreset = Exclude<EventPreset, WholeSeriesEventPreset>;
+export declare const ORDINARY_EVENT_PRESET_VALUES: readonly ["event", "class", "workshop", "retreat", "performance"];
+export declare const WHOLE_SERIES_EVENT_PRESET_VALUES: readonly ["course", "term"];
+export declare const SURFACE_EVENT_PRESET_VALUES: readonly ["class", "course", "term", "workshop", "retreat", "performance"];
+export declare const DEFAULT_EVENT_TYPE_PRESETS: readonly ["event", "class", "course", "term", "workshop", "retreat"];
+export declare const EVENT_SERIES_BEHAVIOURS: readonly ["class", "course", "workshop", "retreat", "performance"];
+/** Keeps Term as Event vocabulary without introducing a second booking engine. */
+export declare function eventPresetForVerticalPreset<TCanonical extends string>(preset: Readonly<{
+    id: string;
+    canonicalBehaviour: TCanonical;
+    eventPresetOverride?: EventPresetOverride;
+}>): TCanonical | EventPresetOverride;

package/dist/_dts/core/src/index.d.ts

@@ -8,6 +8,8 @@ export * from './demo-runtime';
 export * from './collections';
 export * from './event-pricing';
 export * from './event-page-surface-subject';
+export * from './event-page-selection';
+export * from './public-event-booking-availability';
 export * from './money-input';
 export * from './booking-flexible-balance';
 export * from './booking-refunds';
@@ -52,6 +54,10 @@ export * from './slug';
 export * from './string';
 export * from './uuid';
 export * from './stable-json';
+export * from './secret';
 export * from './site-route-target';
 export { disabledSelection, enabledSelection, plannerNoChange, plannerPatch, plannerUpdate, resolvePlanningDateInput, resolvePlanningNow, resolvePlanningNowDate, systemPlanningClock, } from './planner';
 export type { DisabledSelection, EnabledSelection, OptionalSelection, PlannerNoChange, PlannerPatch, PlannerUpdate, PlanningClock, PlanningDateInput, PlanningTimeOptions, } from './planner';
+export { isValidBookingTimeZone, parseBookingTimeZone, type BookingTimeZone, type BookingTimeZoneParseError, } from './booking-time-zone';
+export * from './booking-verticals';
+export * from './event-series-behaviour';

package/dist/_dts/core/src/public-event-booking-availability.d.ts

@@ -0,0 +1,8 @@
+export type PublicEventBookingClosedReason = 'occurrence_cancelled' | 'occurrence_completed' | 'series_draft' | 'series_cancelled' | 'series_completed' | 'series_archived' | 'parent_archived' | 'parent_inconsistent' | 'not_public' | 'already_started' | 'enrollment_closed';
+/** Public wire projection; persisted facts remain authoritative. */
+export type PublicEventBookingAvailability = Readonly<{
+    kind: 'open';
+}> | Readonly<{
+    kind: 'closed';
+    reason: PublicEventBookingClosedReason;
+}>;

package/dist/_dts/core/src/secret.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Credential values that must remain inert when they cross diagnostics,
+ * logging, or serialization boundaries.
+ *
+ * The value is deliberately held behind a non-enumerable capability rather
+ * than exposed as a property. The capability uses a global symbol so a Secret
+ * created by another bundled copy of core remains consumable at an approved
+ * `exposeSecret` boundary.
+ */
+import { type Result } from './result';
+export declare const SECRET_KINDS: readonly ["management-key", "content-key", "preview-key", "webhook-secret", "oauth-access-token", "oauth-refresh-token", "preview-session-refresh-token", "oauth-authorization-code", "oauth-pkce-verifier", "registrar-epp-code"];
+export type SecretKind = (typeof SECRET_KINDS)[number];
+declare const secretBrand: unique symbol;
+declare const secretValueSymbol: unique symbol;
+export declare const SECRET_INSPECT_SYMBOL: unique symbol;
+export type Secret<TKind extends SecretKind> = Readonly<{
+    readonly [secretBrand]: TKind;
+    readonly kind: 'secret';
+    readonly secretType: TKind;
+    readonly toString: () => string;
+    readonly toJSON: () => string;
+    readonly [SECRET_INSPECT_SYMBOL]: () => string;
+    readonly [secretValueSymbol]: () => string;
+}>;
+type PublicSecretKind = Exclude<SecretKind, 'management-key'>;
+export declare const MANAGEMENT_KEY_PREFIX = "bld_mgmt_sk_";
+export type ManagementKeyParseError = Readonly<{
+    readonly kind: 'invalid-management-key';
+}>;
+/** Create an opaque secret after a caller has parsed/validated its boundary. */
+export declare function createSecret<TKind extends PublicSecretKind>(kind: TKind, value: string): Secret<TKind>;
+/**
+ * Parse an untrusted management API key before constructing its Secret value.
+ *
+ * The Secret type protects an already validated value from accidental
+ * disclosure; this boundary is what validates the value's wire format.
+ */
+export declare function parseManagementKey(raw: unknown): Result<Secret<'management-key'>, ManagementKeyParseError>;
+/**
+ * The only generic plaintext exposure operation. Keep calls at named I/O
+ * boundaries; do not pass exposed strings through domain/application layers.
+ */
+export declare function exposeSecret<TKind extends SecretKind>(secret: Secret<TKind>): string;
+export {};