@fanfare-io/fanfare-sdk-core 0.2.0 → 0.4.0

package/dist/test-utils/verification-scenarios.d.ts

@@ -1,8 +1,12 @@
+import { SequenceOutcomeType } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
 import { HarnessScenarioKey } from './harness-scenarios';
-export type VerificationScenarioKey = "queue" | "admission-cycle" | "auth-queue" | "access-code-queue" | "draw" | "auth-draw" | "timed-release" | "auction";
+export type VerificationScenarioKey = "queue" | "admission-cycle" | "appointment" | "auth-queue" | "access-code-queue" | "draw" | "auth-draw" | "timed-release" | "timed-release-completion" | "waitlist-lifecycle" | "auction";
 export type VerificationAction = {
     type: "clickButton";
     label: string;
+} | {
+    type: "clickGridcell";
+    label: string;
 } | {
     type: "fillCredential";
     value: string;
@@ -21,6 +25,10 @@ export interface VerificationCheckpoint {
     visibleActions?: string[];
     hiddenActions?: string[];
     timerVisible?: boolean;
+    waitlistStatus?: "not_waitlisted" | "waitlisted" | "notified";
+    waitlistAbsent?: boolean;
+    /** Pin the ended sequence's outcome type from the bridge snapshot — ended-state copy is shared across most outcomes, so text checkpoints alone cannot distinguish them. */
+    outcomeType?: SequenceOutcomeType;
 }
 export interface VerificationStep {
     key: string;

package/dist/test-utils/verification-scenarios.js

@@ -1 +1 @@
-const e="sdk-harness@example.com",t="424242",i="WRONG1",n="VIP123",s=["queue","admission-cycle","auth-queue","access-code-queue","draw","auth-draw","timed-release","auction"],u=["queue","admission-cycle","auth-queue","access-code-queue","draw","timed-release","auction"],o={queue:{key:"queue",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]},steps:[{key:"entered-queue",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in the Queue","Estimated wait"],hiddenTexts:["Continue to Shop"],visibleActions:["Leave Queue"]}}]},"admission-cycle":{key:"admission-cycle",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]},steps:[{key:"granted",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"granted",visibleTexts:["You're in!","Continue to Shop"],visibleActions:["Continue to Shop"]}}]},"auth-queue":{key:"auth-queue",initial:{journeyStage:"gated",visibleTexts:["Sign In","Enter your email or phone to continue"],visibleActions:["Continue"]},steps:[{key:"submitted-auth-credential",actions:[{type:"fillCredential",value:e},{type:"clickButton",label:"Continue"}],checkpoint:{journeyStage:"gated",visibleTexts:["Enter your code"],visibleActions:["Verify"]}},{key:"verified-auth",actions:[{type:"fillOtp",value:t}],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]}},{key:"entered-queue",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in the Queue","Estimated wait"],visibleActions:["Leave Queue"]}}]},"access-code-queue":{key:"access-code-queue",initial:{journeyStage:"gated",visibleTexts:["Enter Access Code","Enter your access code to continue"],visibleActions:["Submit"],hiddenActions:["Enter Queue"]},steps:[{key:"rejected-access-code",actions:[{type:"fillAccessCode",value:i},{type:"clickButton",label:"Submit"}],checkpoint:{journeyStage:"gated",hiddenActions:["Enter Queue"],visibleActions:["Submit"]}},{key:"unlocked-queue",actions:[{type:"fillAccessCode",value:n},{type:"clickButton",label:"Submit"}],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]}},{key:"entered-queue",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in the Queue","Estimated wait"],visibleActions:["Leave Queue"]}}]},draw:{key:"draw",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Draw"]},steps:[{key:"entered-draw",actions:[{type:"clickButton",label:"Enter Draw"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You've Entered","Good luck in the draw","Drawing in"],visibleActions:["Withdraw Entry"],timerVisible:!0}}]},"auth-draw":{key:"auth-draw",initial:{journeyStage:"gated",visibleTexts:["Sign In","Enter your email or phone to continue"],visibleActions:["Continue"]},steps:[{key:"submitted-auth-credential",actions:[{type:"fillCredential",value:e},{type:"clickButton",label:"Continue"}],checkpoint:{journeyStage:"gated",visibleTexts:["Enter your code"],visibleActions:["Verify"]}},{key:"verified-auth",actions:[{type:"fillOtp",value:t}],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Draw"]}},{key:"entered-draw",actions:[{type:"clickButton",label:"Enter Draw"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You've Entered","Good luck in the draw","Drawing in"],visibleActions:["Withdraw Entry"],timerVisible:!0}}]},"timed-release":{key:"timed-release",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleTexts:["Flash Sale","Limited time access","Window closes in"],visibleActions:["Enter Sale"],timerVisible:!0},steps:[{key:"entered-sale",actions:[{type:"clickButton",label:"Enter Sale"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in!","Complete purchase in","Browse and complete your purchase before your session expires"],visibleActions:["Complete Purchase","Exit Sale"],timerVisible:!0}},{key:"completed-sale",actions:[{type:"clickButton",label:"Complete Purchase"}],checkpoint:{journeyStage:"routed",sequencePhase:"granted",visibleTexts:["You're in!","Continue to Shop"],visibleActions:["Continue to Shop"]}}]},auction:{key:"auction",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleTexts:["Auction","Bid for exclusive access","Auction ends in"],visibleActions:["Bid"],timerVisible:!0},steps:[{key:"bid-auction",actions:[{type:"clickButton",label:"Bid"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["Auction","Current bid","Auction ends in"],visibleActions:["Bid","Leave"],timerVisible:!0}},{key:"placed-bid",actions:[{type:"clickButton",label:"Bid"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're Winning!","Your winning bid","$110.00"],visibleActions:["Bid"]}}]}};function a(e){return e in o}function c(e){return o[e]}export{u as ADAPTER_SMOKE_SCENARIOS,i as DEFAULT_INVALID_ACCESS_CODE,n as DEFAULT_VALID_ACCESS_CODE,e as DEFAULT_VERIFICATION_EMAIL,t as DEFAULT_VERIFICATION_OTP,o as SDK_VERIFICATION_SCENARIOS,s as SHARED_HARNESS_VERIFICATION_SCENARIOS,c as getVerificationScenario,a as isVerificationScenarioKey};
+const e="sdk-harness@example.com",t="424242",i="WRONG1",n="VIP123",s=["queue","admission-cycle","appointment","auth-queue","access-code-queue","draw","auth-draw","timed-release","timed-release-completion","auction"],o=["queue","admission-cycle","auth-queue","access-code-queue","draw","timed-release","auction"],a={queue:{key:"queue",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]},steps:[{key:"entered-queue",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in the Queue","Estimated wait"],hiddenTexts:["Continue to Shop"],visibleActions:["Leave Queue"]}}]},"admission-cycle":{key:"admission-cycle",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]},steps:[{key:"granted",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"granted",visibleTexts:["You're in!","Continue to Shop"],visibleActions:["Continue to Shop"]}}]},appointment:{key:"appointment",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleTexts:["Book an Appointment"],visibleActions:["Select a time"]},steps:[{key:"selected-slot",actions:[{type:"clickGridcell",label:"9:00 AM"}],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",visibleTexts:["Book an Appointment"],visibleActions:["Continue · 9:00 AM"]}},{key:"booked-appointment",actions:[{type:"clickButton",label:"Continue · 9:00 AM"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["Appointment Booked","Suite 100","9:00 AM"],visibleActions:["Reschedule","Cancel"]}},{key:"started-reschedule",actions:[{type:"clickButton",label:"Reschedule"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["Reschedule Appointment"],visibleActions:["Select a time"]}},{key:"selected-reschedule-slot",actions:[{type:"clickGridcell",label:"10:30 AM"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["Reschedule Appointment"],visibleActions:["Continue · 10:30 AM"]}},{key:"rescheduled-appointment",actions:[{type:"clickButton",label:"Continue · 10:30 AM"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["Appointment Booked","Suite 100","10:30 AM"],visibleActions:["Reschedule","Cancel"]}}]},"auth-queue":{key:"auth-queue",initial:{journeyStage:"gated",visibleTexts:["Sign In","Enter your email or phone to continue"],visibleActions:["Continue"]},steps:[{key:"submitted-auth-credential",actions:[{type:"fillCredential",value:e},{type:"clickButton",label:"Continue"}],checkpoint:{journeyStage:"gated",visibleTexts:["Enter your code"],visibleActions:["Verify"]}},{key:"verified-auth",actions:[{type:"fillOtp",value:t}],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]}},{key:"entered-queue",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in the Queue","Estimated wait"],visibleActions:["Leave Queue"]}}]},"access-code-queue":{key:"access-code-queue",initial:{journeyStage:"gated",visibleTexts:["Enter Access Code","Enter your access code to continue"],visibleActions:["Submit"],hiddenActions:["Enter Queue"]},steps:[{key:"rejected-access-code",actions:[{type:"fillAccessCode",value:i},{type:"clickButton",label:"Submit"}],checkpoint:{journeyStage:"gated",hiddenActions:["Enter Queue"],visibleActions:["Submit"]}},{key:"unlocked-queue",actions:[{type:"fillAccessCode",value:n},{type:"clickButton",label:"Submit"}],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Queue"]}},{key:"entered-queue",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in the Queue","Estimated wait"],visibleActions:["Leave Queue"]}}]},draw:{key:"draw",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Draw"]},steps:[{key:"entered-draw",actions:[{type:"clickButton",label:"Enter Draw"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You've Entered","Good luck in the draw","Drawing in"],visibleActions:["Withdraw Entry"],timerVisible:!0}}]},"auth-draw":{key:"auth-draw",initial:{journeyStage:"gated",visibleTexts:["Sign In","Enter your email or phone to continue"],visibleActions:["Continue"]},steps:[{key:"submitted-auth-credential",actions:[{type:"fillCredential",value:e},{type:"clickButton",label:"Continue"}],checkpoint:{journeyStage:"gated",visibleTexts:["Enter your code"],visibleActions:["Verify"]}},{key:"verified-auth",actions:[{type:"fillOtp",value:t}],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",visibleActions:["Enter Draw"]}},{key:"entered-draw",actions:[{type:"clickButton",label:"Enter Draw"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You've Entered","Good luck in the draw","Drawing in"],visibleActions:["Withdraw Entry"],timerVisible:!0}}]},"timed-release":{key:"timed-release",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleTexts:["Flash Sale","Limited time access","Window closes in"],visibleActions:["Enter Sale"],timerVisible:!0},steps:[{key:"entered-sale",actions:[{type:"clickButton",label:"Enter Sale"}],checkpoint:{journeyStage:"routed",sequencePhase:"granted",visibleTexts:["You're in!","Continue to Shop"],visibleActions:["Continue to Shop"],timerVisible:!0}}]},"timed-release-completion":{key:"timed-release-completion",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleTexts:["Flash Sale","Limited time access","Window closes in"],visibleActions:["Enter Sale"],timerVisible:!0},steps:[{key:"entered-grantless-sale",actions:[{type:"clickButton",label:"Enter Sale"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're in!","Complete purchase in","Browse and complete your purchase"],visibleActions:["Complete Purchase"],hiddenActions:["Continue to Shop"],timerVisible:!0}},{key:"completed-sale",actions:[{type:"clickButton",label:"Complete Purchase"}],checkpoint:{journeyStage:"routed",sequencePhase:"ended",outcomeType:"completed",visibleTexts:["Purchase complete","Thank you for your purchase"],hiddenActions:["Complete Purchase","Continue to Shop"]}}]},"waitlist-lifecycle":{key:"waitlist-lifecycle",initial:{journeyStage:"routed",sequencePhase:"scheduled",waitlistStatus:"not_waitlisted",visibleActions:["Enter Waitlist"],hiddenActions:["Enter Queue"]},steps:[{key:"joined-waitlist",actions:[{type:"clickButton",label:"Enter Waitlist"}],checkpoint:{journeyStage:"routed",sequencePhase:"scheduled",waitlistStatus:"waitlisted",visibleTexts:["You're on the Waitlist!"],visibleActions:["Leave Waitlist"],hiddenActions:["Enter Queue"]}},{key:"notified-waitlist",actions:[],checkpoint:{journeyStage:"routed",sequencePhase:"scheduled",waitlistStatus:"notified",visibleActions:["Leave Waitlist"],hiddenActions:["Enter Queue"]}},{key:"opened-queue",actions:[],checkpoint:{journeyStage:"routed",sequencePhase:"enterable",waitlistAbsent:!0,visibleActions:["Enter Queue"],hiddenActions:["Enter Waitlist","Leave Waitlist"]}},{key:"entered-queue",actions:[{type:"clickButton",label:"Enter Queue"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",waitlistAbsent:!0,visibleTexts:["You're in the Queue","Estimated wait"],visibleActions:["Leave Queue"]}}]},auction:{key:"auction",initial:{journeyStage:"routed",sequencePhase:"enterable",visibleTexts:["Auction","Bid for exclusive access","Auction ends in"],visibleActions:["Bid"],timerVisible:!0},steps:[{key:"bid-auction",actions:[{type:"clickButton",label:"Bid"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["Auction","Current bid","Auction ends in"],visibleActions:["Bid","Leave"],timerVisible:!0}},{key:"placed-bid",actions:[{type:"clickButton",label:"Bid"}],checkpoint:{journeyStage:"routed",sequencePhase:"participating",visibleTexts:["You're Winning!","Your winning bid","$110.00"],visibleActions:["Bid"]}}]}};function c(e){return e in a}function u(e){return a[e]}export{o as ADAPTER_SMOKE_SCENARIOS,i as DEFAULT_INVALID_ACCESS_CODE,n as DEFAULT_VALID_ACCESS_CODE,e as DEFAULT_VERIFICATION_EMAIL,t as DEFAULT_VERIFICATION_OTP,a as SDK_VERIFICATION_SCENARIOS,s as SHARED_HARNESS_VERIFICATION_SCENARIOS,u as getVerificationScenario,c as isVerificationScenarioKey};

package/dist/timed-releases/timed-release.driver.d.ts

@@ -0,0 +1,45 @@
+import { DistributionMonitor, MonitorUpdate } from '../experiences/distribution-monitor.types';
+import { DistributionSummary, JourneyEvent, JourneyEventAudience, JourneyEventKind, JourneyEventSeverity, MechanismConsumerState, Participation, SequenceOutcome, SequenceState } from '../experiences/journey.types';
+import { SequenceDriver, SequenceProjectionFacts } from '../experiences/sequence-driver';
+import { TimedReleaseModule } from './types';
+type TimedReleaseMonitorModule = TimedReleaseModule & Pick<DistributionMonitor, "startMonitoring" | "stopMonitoring">;
+/**
+ * Narrow shell and module capabilities required by the timed-release driver.
+ */
+export interface TimedReleaseDriverDependencies {
+    /** Timed-release module functions used by timed-release actions and monitoring. */
+    timedReleases: Pick<TimedReleaseMonitorModule, "enter" | "leave" | "complete" | "startMonitoring" | "stopMonitoring">;
+    /** Serialize a timed-release action with the shell's operation queue. */
+    runSerializedOperation(operation: () => Promise<void>): Promise<void>;
+    /** Read the current routed sequence before validating a timed-release action. */
+    getCurrentSequence(): SequenceState | undefined;
+    /** Commit a concrete next timed-release sequence into the shell. */
+    commit(next: SequenceState, opts?: {
+        events?: JourneyEvent[];
+    }): void;
+    /** Apply shell-owned grant and terminal lifecycle side effects. */
+    applyMonitorUpdate(update: MonitorUpdate): void;
+    /** Ensure the shell-owned display atom exists for this timed-release participation. */
+    ensureDisplayAtom(participation: Participation): void;
+    /** Stop shell runtime monitoring and optionally clear display state. */
+    stopRuntimeMonitoring(clearDisplay?: boolean): void;
+    /** Append a shell-visible journey event to the snapshot. */
+    emitEvent(kind: JourneyEventKind, severity: JourneyEventSeverity, audience: JourneyEventAudience, message: string, detail?: Record<string, unknown>): void;
+}
+/**
+ * Create the timed-release sequence driver for one journey instance.
+ */
+export declare function createTimedReleaseDriver(deps: TimedReleaseDriverDependencies): SequenceDriver;
+/**
+ * Project timed-release server facts into a timed-release sequence state.
+ */
+export declare function projectTimedReleaseSequence(facts: SequenceProjectionFacts): SequenceState;
+/**
+ * Return the timed-release consumer state that represents an issued grant.
+ */
+export declare function withTimedReleaseGrantedConsumer(consumer: MechanismConsumerState | undefined, distribution: DistributionSummary): MechanismConsumerState;
+/**
+ * Return the timed-release consumer state that represents a terminal outcome.
+ */
+export declare function withTimedReleaseTerminalConsumer(consumer: MechanismConsumerState | undefined, outcome?: SequenceOutcome): MechanismConsumerState | undefined;
+export {};

package/dist/timed-releases/timed-release.driver.js

@@ -0,0 +1 @@
+import{createError as e}from"../core/errors.js";function t(e){return new r(e)}function i(t){const{distribution:i,consumer:s,waitlist:n,grant:r,outcome:o}=t;if(!i)return{phase:"unavailable"};const c=function(t){if("timed_release"!==t.type)throw e.validationError("Timed-release driver received a non-timed-release distribution");return t}(i),u=s&&"timed_release"===s.mechanism?function(e){const{mechanism:t,...i}=e;return i}(s):a(i);if(r)return"completed"===o?.type?d(c,u,o):r.expiresAt&&Date.now()>new Date(r.expiresAt).getTime()?"open"===c.lifecycle?{phase:"enterable",mechanism:"timed_release",distribution:c,consumer:a(c)}:d(c,u,{type:"expired"}):{phase:"granted",mechanism:"timed_release",distribution:c,consumer:u,grant:r};const m=o??function(e){return"completed"===e.status?{type:"completed"}:"denied"===e.status?{type:"denied",reason:e.deniedReason}:"left"===e.status?{type:"left"}:void 0}(u);if(m)return d(c,u,m);if(function(e){return"entered"===e.status}(u))return{phase:"participating",mechanism:"timed_release",distribution:c,consumer:u};if("scheduled"===c.lifecycle){const e=n&&n.waitlistId===c.waitlistId?n:c.waitlistId?{waitlistId:c.waitlistId,status:"not_waitlisted"}:void 0;return{phase:"scheduled",mechanism:"timed_release",distribution:c,...e?{waitlist:e}:{}}}return"open"===c.lifecycle?{phase:"enterable",mechanism:"timed_release",distribution:c,consumer:u}:d(c,u,{type:"closed"})}function s(e,t){return"timed_release"===e?.mechanism?{...e,status:"completed"}:{mechanism:"timed_release",status:"completed",id:t.id,distributionId:t.id}}function n(e,t){return e&&"timed_release"===e.mechanism&&t?"left"===t.type?{...e,status:"left"}:"denied"===t.type?{...e,status:"denied",deniedReason:t.reason}:"completed"===t.type?{...e,status:"completed"}:{...e,status:"not_entered"}:e}class r{constructor(e){this.deps=e,this.mechanism="timed_release"}project(e){return i(e)}buildView(t,i){if("unavailable"===t.phase)return{phase:"unavailable",reason:t.reason};const s=function(t){if(!("mechanism"in t)||"timed_release"!==t.mechanism)throw e.validationError("Timed-release driver received a non-timed-release sequence");return t}(t);switch(s.phase){case"scheduled":return{phase:"scheduled",mechanism:"timed_release",distribution:s.distribution,startsAt:s.distribution.startsAt??s.distribution.opensAt,waitlist:s.waitlist?{status:s.waitlist.status,join:()=>i.joinWaitlist(),leave:()=>i.exitWaitlist()}:void 0};case"enterable":return{phase:"enterable",mechanism:"timed_release",distribution:s.distribution,consumer:s.consumer,enter:()=>this.enter()};case"participating":return{phase:"participating",mechanism:"timed_release",consumer:s.consumer,display$:i.displayAtom,leave:()=>this.leave(),complete:()=>this.complete()};case"granted":return{phase:"granted",mechanism:"timed_release",distribution:s.distribution,consumer:s.consumer,grant:s.grant,claim:()=>i.claim()};case"ended":return{phase:"ended",mechanism:"timed_release",consumer:s.consumer,outcome:s.outcome}}}startMonitoring(e){this.activeMonitorId=e.participation.id,this.deps.timedReleases.startMonitoring(e.participation.id,{displayAtom:e.displayAtom},e.onUpdate)}stopMonitoring(){this.activeMonitorId&&(this.deps.timedReleases.stopMonitoring(this.activeMonitorId),this.activeMonitorId=void 0)}async enter(){await this.deps.runSerializedOperation(async()=>{await this.enterWithinOperation()})}async enterWithinOperation(){const e=this.currentTimedReleaseSequence("enterable","No open timed release to enter").distribution,t=function(e){if("ENTERED"===e.status)return e.admissionGrant?{type:"granted",token:e.admissionGrant,expiresAt:e.expiresAt?new Date(e.expiresAt).getTime():void 0}:null;if("COMPLETED"===e.status)return{type:"ended",outcome:{type:"completed"}};return{type:"ended",outcome:{type:"LEFT"===e.status?"left":"denied",reason:"reason"in e?e.reason:void 0}}}(await this.deps.timedReleases.enter(e.id,void 0));if(t)return void this.deps.applyMonitorUpdate(t);const s={mechanism:"timed_release",status:"entered",id:n=e.id,distributionId:n};var n;this.deps.ensureDisplayAtom({id:e.id,type:"timed_release"}),this.deps.commit(i({distribution:e,consumer:s})),this.deps.emitEvent("sequence_change","success","user","Entered timed release",{distributionId:e.id})}async leave(){await this.deps.runSerializedOperation(async()=>{await this.leaveWithinOperation()})}async leaveWithinOperation(){const e=this.currentTimedReleaseSequence("participating"),t=e.consumer.distributionId??e.consumer.id??e.distribution.id;this.deps.stopRuntimeMonitoring(!0),await this.deps.timedReleases.leave(t),this.deps.applyMonitorUpdate({type:"ended",outcome:{type:"left"}}),this.deps.emitEvent("sequence_change","info","user","Left participation",{type:"timed_release"})}async complete(){await this.deps.runSerializedOperation(async()=>{const e=this.currentTimedReleaseSequence("participating"),t=e.consumer.distributionId??e.consumer.id??e.distribution.id,i=this.deps.timedReleases.complete(t);i?this.deps.applyMonitorUpdate({type:"granted",token:i}):this.deps.applyMonitorUpdate({type:"ended",outcome:{type:"completed"}}),this.deps.emitEvent("sequence_change","success","user","Completed timed release",{timedReleaseId:t})})}currentTimedReleaseSequence(t,i="Not participating in a timed release"){const s=this.deps.getCurrentSequence();if(!s||s.phase!==t||!("mechanism"in s)||"timed_release"!==s.mechanism)throw e.validationError(i);return s}}function a(e){return{status:"not_entered",distributionId:e.id}}function d(e,t,i){return{phase:"ended",mechanism:"timed_release",distribution:e,consumer:t,outcome:{...i,distributionType:i.distributionType??e.type,distributionId:i.distributionId??e.id,at:i.at??/* @__PURE__ */(new Date).toISOString()}}}export{t as createTimedReleaseDriver,i as projectTimedReleaseSequence,s as withTimedReleaseGrantedConsumer,n as withTimedReleaseTerminalConsumer};

package/dist/timed-releases/timed-release.module.d.ts

@@ -16,7 +16,12 @@ export declare class TimedReleaseManagementModule implements TimedReleaseModule
     get(timedReleaseId: string): Promise<TimedRelease>;
     enter(timedReleaseId: string, variantId?: string, options?: RequestOptions): Promise<TimedReleaseConsumerState>;
     leave(timedReleaseId: string, options?: RequestOptions): Promise<void>;
-    complete(timedReleaseId: string, options?: RequestOptions): Promise<string | undefined>;
+    /**
+     * Admit = enter: the admission credential is minted and returned at entry, so
+     * finishing makes no network call — it resolves the credential held from entry
+     * (and refreshed by status re-mints) for the checkout claim.
+     */
+    complete(timedReleaseId: string): string | undefined;
     status(timedReleaseId: string): Promise<TimedReleaseConsumerState>;
     startMonitoring(id: string, context?: Record<string, unknown>, onUpdate?: (update: MonitorUpdate) => void): void;
     stopMonitoring(id: string): void;

package/dist/timed-releases/timed-release.module.js

@@ -1 +1 @@
-import{createError as t}from"../core/errors.js";import{getLogger as e}from"../core/logger.js";import{DistributionMonitorRuntime as i}from"../experiences/distribution-monitor.runtime.js";import{getEventBus as s}from"../state/events.js";import{getSDKStore as r}from"../state/store.js";class n{constructor(t){this.logger=e(),this.events=s(),this.monitorRuntime=new i,this.trackedParticipations=/* @__PURE__ */new Map,this.monitorGenerations=/* @__PURE__ */new Map,this.operationGenerations=/* @__PURE__ */new Map,this.destroyed=!1,this.lifecycleGeneration=0,this.http=t}get store(){return r()}async get(t){try{return await this.http.get(`/timed-releases/${t}`)}catch(e){throw this.logger.error("Failed to get timed release",{timedReleaseId:t,error:e}),e}}async enter(e,i,s){const r=this.lifecycleGeneration,n=this.monitorGenerations.get(e);if(!this.store.session)throw t.unauthorized("Not authenticated. Call auth.guest() or auth.login() first");const o=this.bumpOperationGeneration(e);try{this.logger.info("Entering timed release",{timedReleaseId:e});const t=await this.http.post(`/timed-releases/${e}/enter`,{variantId:i},s),a=this.buildTransition(e,t,{source:"enter"});return this.canApplyAsyncResult(e,r,n,o)?(this.applyTransition(e,a),t):t}catch(a){if(!this.canApplyAsyncResult(e,r,n,o))throw a;throw this.logger.error("Failed to enter timed release",{timedReleaseId:e,error:a}),this.events.emit("timed_release:error",{timedReleaseId:e,error:a}),a}}async leave(t,e){const i=this.lifecycleGeneration,s=this.monitorGenerations.get(t),r=this.bumpOperationGeneration(t);try{this.logger.info("Leaving timed release",{timedReleaseId:t}),await this.http.post(`/timed-releases/${t}/leave`,{},e);const n=this.buildTransition(t,{status:"LEFT",leftAt:/* @__PURE__ */(new Date).toISOString()},{source:"leave"});if(!this.canApplyAsyncResult(t,i,s,r))return;this.applyTransition(t,n)}catch(n){if(!this.canApplyAsyncResult(t,i,s,r))throw n;throw this.logger.error("Failed to leave timed release",{timedReleaseId:t,error:n}),this.events.emit("timed_release:error",{timedReleaseId:t,error:n}),n}}async complete(t,e){const i=this.lifecycleGeneration,s=this.monitorGenerations.get(t),r=this.bumpOperationGeneration(t);try{this.logger.info("Completing timed release",{timedReleaseId:t});const n=(await this.http.post(`/timed-releases/${t}/complete`,{},e)).admissionGrant,o=this.buildTransition(t,{status:"COMPLETED",completedAt:/* @__PURE__ */(new Date).toISOString()},{source:"complete",grant:n});return this.canApplyAsyncResult(t,i,s,r)?(this.applyTransition(t,o),n):n}catch(n){if(!this.canApplyAsyncResult(t,i,s,r))throw n;throw this.logger.error("Failed to complete timed release",{timedReleaseId:t,error:n}),this.events.emit("timed_release:error",{timedReleaseId:t,error:n}),n}}async status(t){const e=this.lifecycleGeneration,i=this.monitorGenerations.get(t),s=this.bumpOperationGeneration(t);try{const r=await this.http.get(`/timed-releases/${t}/status`),n=this.buildTransition(t,r,{source:"status"});return this.canApplyAsyncResult(t,e,i,s)?(this.applyTransition(t,n),this.events.emit("timed_release:status-updated",{timedReleaseId:t,status:r.status}),r):r}catch(r){if(r&&"object"==typeof r&&"status"in r&&404===r.status){const r={status:"NOT_ENTERED"},n=this.buildTransition(t,r,{source:"status"});return this.canApplyAsyncResult(t,e,i,s)?(this.applyTransition(t,n),this.events.emit("timed_release:status-updated",{timedReleaseId:t,status:r.status}),r):r}if(!this.canApplyAsyncResult(t,e,i,s))return{status:"NOT_ENTERED"};throw this.logger.error("Failed to get timed release status",{timedReleaseId:t,error:r}),this.events.emit("timed_release:error",{timedReleaseId:t,error:r}),r}}startMonitoring(t,e,i){this.bumpMonitorGeneration(t),this.monitorRuntime.start(t,e,i);const s=this.monitorRuntime.getDisplayAtom(t);s&&s.set({type:"timed_release",enteredAt:this.trackedParticipations.get(t)?.enteredAt})}stopMonitoring(t){this.bumpMonitorGeneration(t),this.monitorRuntime.stop(t)}isMonitoring(t){return this.monitorRuntime.has(t)}bumpMonitorGeneration(t){const e=(this.monitorGenerations.get(t)??0)+1;return this.monitorGenerations.set(t,e),e}getOperationGeneration(t){return this.operationGenerations.get(t)??0}bumpOperationGeneration(t){const e=this.getOperationGeneration(t)+1;return this.operationGenerations.set(t,e),e}canApplyAsyncResult(t,e,i,s){return!this.destroyed&&this.lifecycleGeneration===e&&((void 0===i||this.monitorGenerations.get(t)===i)&&(void 0===s||this.getOperationGeneration(t)===s))}buildTransition(t,e,{source:i,grant:s}){switch(e.status){case"ENTERED":return{trackedParticipation:{timedReleaseId:t,enteredAt:e.enteredAt,selectedVariantId:e.selectedVariantId},events:"enter"===i?[{type:"timed_release:entered",payload:{timedReleaseId:t,enteredAt:e.enteredAt}}]:[],monitorUpdate:null,stopMonitoring:!1};case"COMPLETED":return{trackedParticipation:null,events:[{type:"timed_release:completed",payload:{timedReleaseId:t,completedAt:e.completedAt}}],monitorUpdate:"complete"===i&&s?{type:"granted",token:s}:null,stopMonitoring:"complete"===i||"status"===i};case"LEFT":return{trackedParticipation:null,events:[{type:"timed_release:left",payload:{timedReleaseId:t}}],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"left"}}:null,stopMonitoring:"leave"===i||"status"===i};case"DENIED":return{trackedParticipation:null,events:[],monitorUpdate:"enter"===i||"status"===i?{type:"ended",outcome:{type:"denied",reason:e.reason}}:null,stopMonitoring:"enter"===i||"status"===i};case"NOT_ENTERED":return{trackedParticipation:null,events:[],monitorUpdate:"enter"===i||"status"===i?{type:"ended",outcome:{type:"closed",reason:"not_entered"}}:null,stopMonitoring:"enter"===i||"status"===i}}}applyTransition(t,e){e.trackedParticipation?this.trackedParticipations.set(t,e.trackedParticipation):this.trackedParticipations.delete(t);const i=this.monitorRuntime.getDisplayAtom(t);i&&(e.trackedParticipation?i.set({type:"timed_release",enteredAt:e.trackedParticipation.enteredAt}):i.set({type:"timed_release"}));for(const s of e.events)this.events.emit(s.type,s.payload);e.monitorUpdate&&this.monitorRuntime.notify(t,e.monitorUpdate),e.stopMonitoring&&this.stopMonitoring(t)}destroy(){this.destroyed=!0,this.lifecycleGeneration+=1,this.trackedParticipations.clear(),this.monitorGenerations.clear(),this.operationGenerations.clear(),this.monitorRuntime.clear()}}export{n as TimedReleaseManagementModule};
+import{createError as t}from"../core/errors.js";import{getLogger as e}from"../core/logger.js";import{DistributionMonitorRuntime as i}from"../experiences/distribution-monitor.runtime.js";import{getEventBus as s}from"../state/events.js";import{getSDKStore as r}from"../state/store.js";class n{constructor(t){this.logger=e(),this.events=s(),this.monitorRuntime=new i,this.trackedParticipations=/* @__PURE__ */new Map,this.monitorGenerations=/* @__PURE__ */new Map,this.operationGenerations=/* @__PURE__ */new Map,this.destroyed=!1,this.lifecycleGeneration=0,this.http=t}get store(){return r()}async get(t){try{return await this.http.get(`/timed-releases/${t}`)}catch(e){throw this.logger.error("Failed to get timed release",{timedReleaseId:t,error:e}),e}}async enter(e,i,s){const r=this.lifecycleGeneration,n=this.monitorGenerations.get(e);if(!this.store.session)throw t.unauthorized("Not authenticated. Call auth.guest() or auth.login() first");const o=this.bumpOperationGeneration(e);try{this.logger.info("Entering timed release",{timedReleaseId:e});const t=await this.http.post(`/timed-releases/${e}/enter`,{variantId:i},s),a=this.buildTransition(e,t,{source:"enter"});return this.canApplyAsyncResult(e,r,n,o)?(this.applyTransition(e,a),t):t}catch(a){if(!this.canApplyAsyncResult(e,r,n,o))throw a;throw this.logger.error("Failed to enter timed release",{timedReleaseId:e,error:a}),this.events.emit("timed_release:error",{timedReleaseId:e,error:a}),a}}async leave(t,e){const i=this.lifecycleGeneration,s=this.monitorGenerations.get(t),r=this.bumpOperationGeneration(t);try{this.logger.info("Leaving timed release",{timedReleaseId:t}),await this.http.post(`/timed-releases/${t}/leave`,{},e);const n=this.buildTransition(t,{status:"LEFT",leftAt:/* @__PURE__ */(new Date).toISOString()},{source:"leave"});if(!this.canApplyAsyncResult(t,i,s,r))return;this.applyTransition(t,n)}catch(n){if(!this.canApplyAsyncResult(t,i,s,r))throw n;throw this.logger.error("Failed to leave timed release",{timedReleaseId:t,error:n}),this.events.emit("timed_release:error",{timedReleaseId:t,error:n}),n}}complete(t){return this.trackedParticipations.get(t)?.admissionGrant}async status(t){const e=this.lifecycleGeneration,i=this.monitorGenerations.get(t),s=this.bumpOperationGeneration(t);try{const r=await this.http.get(`/timed-releases/${t}/status`),n=this.buildTransition(t,r,{source:"status"});return this.canApplyAsyncResult(t,e,i,s)?(this.applyTransition(t,n),this.events.emit("timed_release:status-updated",{timedReleaseId:t,status:r.status}),r):r}catch(r){if(r&&"object"==typeof r&&"status"in r&&404===r.status){const r={status:"NOT_ENTERED"},n=this.buildTransition(t,r,{source:"status"});return this.canApplyAsyncResult(t,e,i,s)?(this.applyTransition(t,n),this.events.emit("timed_release:status-updated",{timedReleaseId:t,status:r.status}),r):r}if(!this.canApplyAsyncResult(t,e,i,s))return{status:"NOT_ENTERED"};throw this.logger.error("Failed to get timed release status",{timedReleaseId:t,error:r}),this.events.emit("timed_release:error",{timedReleaseId:t,error:r}),r}}startMonitoring(t,e,i){this.bumpMonitorGeneration(t),this.monitorRuntime.start(t,e,i);const s=this.monitorRuntime.getDisplayAtom(t);s&&s.set({type:"timed_release",enteredAt:this.trackedParticipations.get(t)?.enteredAt})}stopMonitoring(t){this.bumpMonitorGeneration(t),this.monitorRuntime.stop(t)}isMonitoring(t){return this.monitorRuntime.has(t)}bumpMonitorGeneration(t){const e=(this.monitorGenerations.get(t)??0)+1;return this.monitorGenerations.set(t,e),e}getOperationGeneration(t){return this.operationGenerations.get(t)??0}bumpOperationGeneration(t){const e=this.getOperationGeneration(t)+1;return this.operationGenerations.set(t,e),e}canApplyAsyncResult(t,e,i,s){return!this.destroyed&&this.lifecycleGeneration===e&&((void 0===i||this.monitorGenerations.get(t)===i)&&(void 0===s||this.getOperationGeneration(t)===s))}buildTransition(t,e,{source:i}){switch(e.status){case"ENTERED":return{trackedParticipation:{timedReleaseId:t,enteredAt:e.enteredAt,selectedVariantId:e.selectedVariantId,admissionGrant:e.admissionGrant,expiresAt:e.expiresAt},events:"enter"===i?[{type:"timed_release:entered",payload:{timedReleaseId:t,enteredAt:e.enteredAt}}]:[],monitorUpdate:e.admissionGrant?{type:"granted",token:e.admissionGrant,expiresAt:e.expiresAt?new Date(e.expiresAt).getTime():void 0}:null,stopMonitoring:!1};case"COMPLETED":return{trackedParticipation:null,events:[{type:"timed_release:completed",payload:{timedReleaseId:t,completedAt:e.completedAt}}],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"completed"}}:null,stopMonitoring:"status"===i};case"LEFT":return{trackedParticipation:null,events:[{type:"timed_release:left",payload:{timedReleaseId:t}}],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"left"}}:null,stopMonitoring:"leave"===i||"status"===i};case"DENIED":return{trackedParticipation:null,events:[],monitorUpdate:"enter"===i||"status"===i?{type:"ended",outcome:{type:"denied",reason:e.reason}}:null,stopMonitoring:"enter"===i||"status"===i};case"NOT_ENTERED":return{trackedParticipation:null,events:[],monitorUpdate:"enter"===i||"status"===i?{type:"ended",outcome:{type:"closed",reason:"not_entered"}}:null,stopMonitoring:"enter"===i||"status"===i}}}applyTransition(t,e){e.trackedParticipation?this.trackedParticipations.set(t,e.trackedParticipation):this.trackedParticipations.delete(t);const i=this.monitorRuntime.getDisplayAtom(t);i&&(e.trackedParticipation?i.set({type:"timed_release",enteredAt:e.trackedParticipation.enteredAt}):i.set({type:"timed_release"}));for(const s of e.events)this.events.emit(s.type,s.payload);e.monitorUpdate&&this.monitorRuntime.notify(t,e.monitorUpdate),e.stopMonitoring&&this.stopMonitoring(t)}destroy(){this.destroyed=!0,this.lifecycleGeneration+=1,this.trackedParticipations.clear(),this.monitorGenerations.clear(),this.operationGenerations.clear(),this.monitorRuntime.clear()}}export{n as TimedReleaseManagementModule};

package/dist/timed-releases/timed-release.sequence.d.ts

@@ -0,0 +1,227 @@
+import { AdmissionGrant, SequenceOutcome, TimedReleaseConsumerStatus } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
+import { ReadableAtom } from 'nanostores';
+import { TimedReleaseDisplayState } from '../experiences/distribution-monitor.types';
+import { DistributionSummary, WaitlistAttachment, WaitlistAttachmentView } from '../experiences/journey.types';
+/**
+ * Timed release participation facts for one consumer.
+ *
+ * The server is authoritative for every field. Timestamps are ISO 8601 strings.
+ * Optional fields are present only after the matching timed release lifecycle
+ * event has occurred.
+ */
+export interface TimedReleaseSequenceConsumerState {
+    /** Server timed release status for this consumer. */
+    status: TimedReleaseConsumerStatus;
+    /** Timed release participation id, when the server has created one. */
+    id?: string;
+    /** Distribution id this timed release participation belongs to. */
+    distributionId?: string;
+    /** ISO 8601 timestamp for when the consumer entered the timed release. */
+    enteredAt?: string;
+    /** Opaque admission credential token, when one has been issued inline. */
+    admissionGrant?: string;
+    /** ISO 8601 timestamp for when the consumer was granted admission. */
+    grantedAt?: string;
+    /** Server-provided denial reason for denied timed release outcomes. */
+    deniedReason?: string;
+}
+/**
+ * A timed release sequence as seen by one consumer.
+ *
+ * Lifecycle: scheduled -> enterable -> participating -> granted -> ended. Entry
+ * reserves the timed release position, the participating display tracks the
+ * live release window, and completion may surface the held admission grant.
+ */
+export type TimedReleaseSequence = TimedReleaseScheduled | TimedReleaseEnterable | TimedReleaseParticipating | TimedReleaseGranted | TimedReleaseEnded;
+/**
+ * The timed release exists but entry has not opened yet.
+ */
+export interface TimedReleaseScheduled {
+    /** Mechanism discriminator for timed release narrowing. */
+    mechanism: "timed_release";
+    /** Phase discriminator; scheduled timed releases cannot be entered yet. */
+    phase: "scheduled";
+    /** Timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** Scheduled-only waitlist attachment, cleared when the timed release opens. */
+    waitlist?: WaitlistAttachment;
+}
+/**
+ * The timed release is open and this consumer has not entered it.
+ */
+export interface TimedReleaseEnterable {
+    /** Mechanism discriminator for timed release narrowing. */
+    mechanism: "timed_release";
+    /** Phase discriminator; `enter()` is legal on the matching view. */
+    phase: "enterable";
+    /** Open timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** Consumer timed release facts before entry. */
+    consumer: TimedReleaseSequenceConsumerState;
+}
+/**
+ * The consumer has entered the timed release.
+ */
+export interface TimedReleaseParticipating {
+    /** Mechanism discriminator for timed release narrowing. */
+    mechanism: "timed_release";
+    /** Phase discriminator; timed release display is live while participating. */
+    phase: "participating";
+    /** Timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** Consumer timed release participation facts. */
+    consumer: TimedReleaseSequenceConsumerState;
+}
+/**
+ * The timed release has issued an admission grant to this consumer.
+ */
+export interface TimedReleaseGranted {
+    /** Mechanism discriminator for timed release narrowing. */
+    mechanism: "timed_release";
+    /** Phase discriminator; `claim()` is legal on the matching view. */
+    phase: "granted";
+    /** Timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** Consumer timed release facts associated with the grant. */
+    consumer: TimedReleaseSequenceConsumerState;
+    /** Admission credential issued by the server for this timed release. */
+    grant: AdmissionGrant;
+}
+/**
+ * The timed release journey is terminal for this consumer.
+ */
+export interface TimedReleaseEnded {
+    /** Mechanism discriminator for timed release narrowing. */
+    mechanism: "timed_release";
+    /** Phase discriminator; no timed release actions are legal after this phase. */
+    phase: "ended";
+    /** Timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** Consumer timed release facts at the terminal outcome. */
+    consumer: TimedReleaseSequenceConsumerState;
+    /** Server-derived terminal outcome for the timed release participation. */
+    outcome: SequenceOutcome;
+}
+/**
+ * Timed release views exposed by `JourneyView.sequence`.
+ *
+ * The view lifecycle mirrors the timed release sequence lifecycle. Actions exist
+ * only on the phases where they are legal, and each action may reject if the
+ * server has moved the sequence before the request is handled.
+ */
+export type TimedReleaseSequenceView = TimedReleaseScheduledView | TimedReleaseEnterableView | TimedReleaseParticipatingView | TimedReleaseGrantedView | TimedReleaseEndedView;
+/**
+ * Scheduled timed release view rendered before entry opens.
+ */
+export interface TimedReleaseScheduledView {
+    /** Phase discriminator; no timed release action is legal yet. */
+    phase: "scheduled";
+    /** Mechanism discriminator for timed release rendering. */
+    mechanism: "timed_release";
+    /** Timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** ISO 8601 opening timestamp chosen from the distribution start/open time. */
+    startsAt?: string;
+    /** Scheduled-only waitlist actions; this attachment never grants access. */
+    waitlist?: WaitlistAttachmentView;
+}
+/**
+ * Enterable timed release view rendered when the consumer can enter.
+ */
+export interface TimedReleaseEnterableView {
+    /** Phase discriminator; `enter()` is legal on this view. */
+    phase: "enterable";
+    /** Mechanism discriminator for timed release rendering. */
+    mechanism: "timed_release";
+    /** Open timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** Consumer timed release facts before entry. */
+    consumer: TimedReleaseSequenceConsumerState;
+    /**
+     * Enter the timed release.
+     *
+     * Legal only while this view is current. The promise rejects if entry is no
+     * longer allowed or the server rejects the participation request.
+     */
+    enter(): Promise<void>;
+}
+/**
+ * Participating timed release view rendered after entry.
+ */
+export interface TimedReleaseParticipatingView {
+    /** Phase discriminator; `leave()` and `complete()` are legal on this view. */
+    phase: "participating";
+    /** Mechanism discriminator for timed release rendering. */
+    mechanism: "timed_release";
+    /** Consumer timed release participation facts. */
+    consumer: TimedReleaseSequenceConsumerState;
+    /** Live timed release display facts, such as release timing and availability. */
+    display$: ReadableAtom<TimedReleaseDisplayState>;
+    /**
+     * Leave the timed release participation.
+     *
+     * Legal only while this view is current. The promise rejects if the consumer
+     * is no longer participating or the server rejects the leave request.
+     */
+    leave(): Promise<void>;
+    /**
+     * Complete the timed release participation.
+     *
+     * Legal only while this view is current. The promise rejects if completion is
+     * no longer allowed; success moves the journey to granted or ended depending
+     * on the server-held credential.
+     */
+    complete(): Promise<void>;
+}
+/**
+ * Granted timed release view rendered after completion exposes a credential.
+ */
+export interface TimedReleaseGrantedView {
+    /** Phase discriminator; `claim()` is legal on this view. */
+    phase: "granted";
+    /** Mechanism discriminator for timed release rendering. */
+    mechanism: "timed_release";
+    /** Timed release distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "timed_release";
+    };
+    /** Consumer timed release facts associated with the grant. */
+    consumer: TimedReleaseSequenceConsumerState;
+    /** Admission credential issued by the server for this timed release. */
+    grant: AdmissionGrant;
+    /**
+     * Claim the timed release admission credential for handoff.
+     *
+     * Legal only while this view is current. It returns the credential
+     * synchronously and may throw if the journey has already left the granted
+     * phase.
+     */
+    claim(): AdmissionGrant;
+}
+/**
+ * Ended timed release view rendered once the journey is terminal.
+ */
+export interface TimedReleaseEndedView {
+    /** Phase discriminator; no timed release action is legal after this phase. */
+    phase: "ended";
+    /** Mechanism discriminator for timed release rendering. */
+    mechanism: "timed_release";
+    /** Consumer timed release facts at the terminal outcome. */
+    consumer: TimedReleaseSequenceConsumerState;
+    /** Server-derived terminal outcome for the timed release participation. */
+    outcome: SequenceOutcome;
+}

package/dist/timed-releases/types.d.ts

@@ -21,6 +21,9 @@ export interface TimedReleaseParticipation {
     timedReleaseId: string;
     enteredAt: string;
     selectedVariantId?: string;
+    /** Admission credential held from entry; refreshed on every status re-mint. */
+    admissionGrant?: string;
+    expiresAt?: string;
 }
 /**
  * Timed Release consumer states (from backend)
@@ -33,6 +36,13 @@ export interface TimedReleaseEnteredState {
     status: "ENTERED";
     enteredAt: string;
     selectedVariantId?: string;
+    /**
+     * Admit = enter: the admission credential is minted at entry and held from
+     * then on. Status reads re-mint it statelessly (a byte-different token with the
+     * same standing).
+     */
+    admissionGrant?: string;
+    expiresAt?: string;
 }
 export interface TimedReleaseCompletedState {
     status: "COMPLETED";
@@ -55,7 +65,12 @@ export interface TimedReleaseModule {
     get(timedReleaseId: string): Promise<TimedRelease>;
     enter(timedReleaseId: string, variantId?: string, options?: RequestOptions): Promise<TimedReleaseConsumerState>;
     leave(timedReleaseId: string, options?: RequestOptions): Promise<void>;
-    complete(timedReleaseId: string, options?: RequestOptions): Promise<string | undefined>;
+    /**
+     * Admit = enter: resolves the admission credential held from entry for the
+     * checkout claim. No network call — the credential was minted and returned at
+     * entry and refreshed by status re-mints.
+     */
+    complete(timedReleaseId: string): string | undefined;
     status(timedReleaseId: string): Promise<TimedReleaseConsumerState>;
 }
 /**

package/dist/types/distribution-type.d.ts

@@ -35,7 +35,7 @@ export type SdkHandoffDistributionType = Exclude<SdkDistributionType, "timed_rel
 /**
  * Distribution types that participate in journey resume / participation tracking.
  */
-export type SdkJourneyParticipationType = SdkDistributionType;
+export type SdkJourneyParticipationType = SdkDistributionEntryType;
 /**
  * Distribution types that produce admissions for journey resume.
  * Excludes `appointment` (booking is the participation; there is no admission

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * SDK version
  * This is automatically updated during the build process
  */
-export declare const version = "0.2.0";
+export declare const version = "0.4.0";

package/dist/version.js

@@ -1 +1 @@
-const o="0.2.0";export{o as version};
+const o="0.4.0";export{o as version};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Official Fanfare Browser SDK for queue, draw, auction, and appointment experiences",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -122,7 +122,7 @@
     "uuid": "^14.0.0",
     "wretch": "^2.11.0",
     "zustand": "^5.0.6",
-    "@fanfare-io/fanfare-sdk-contracts": "0.2.0"
+    "@fanfare-io/fanfare-sdk-contracts": "0.4.0"
   },
   "peerDependencies": {
     "valibot": "^1.1.0",
@@ -165,7 +165,7 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4",
-    "@fanfare-io/shared-models": "0.2.0"
+    "@fanfare-io/shared-models": "0.4.0"
   },
   "sideEffects": false,
   "keywords": [