@mpgd/adapter-devvit 0.4.0 → 0.5.0

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+export * from './post-operation.js';
+export * from './redis-post-operation-store.js';

package/dist/server/index.js

@@ -0,0 +1,2 @@
+export * from './post-operation.js';
+export * from './redis-post-operation-store.js';

package/dist/server/post-operation.d.ts

@@ -0,0 +1,135 @@
+declare const operationSchemaVersion: 1;
+export type DevvitJsonValue = null | boolean | number | string | readonly DevvitJsonValue[] | DevvitJsonObject;
+export interface DevvitJsonObject {
+  readonly [key: string]: DevvitJsonValue;
+}
+export interface DevvitDurableOperationStore {
+  /** Reads one durable value. Missing values return undefined. */
+  read(key: string): Promise<string | undefined>;
+  /** Atomically creates a value only when the key is absent. */
+  create(key: string, value: string): Promise<boolean>;
+  /** Atomically replaces a value only when its raw current value matches. */
+  compareAndSet(key: string, expectedValue: string, nextValue: string): Promise<boolean>;
+  /** Atomically creates an expiring reconciliation lease. */
+  createLease(key: string, token: string, expiresAt: Date): Promise<boolean>;
+  /** Deletes a lease only when the current token matches. */
+  releaseLease(key: string, token: string): Promise<void>;
+}
+export interface DevvitPostOperationScope {
+  readonly appScope: string;
+  /** Use the canonical subreddit identifier, not a display name. */
+  readonly subredditId: string;
+}
+export interface DevvitPostLaunch<TParams extends DevvitJsonObject> {
+  readonly entry: string;
+  readonly params: TParams;
+}
+export interface DevvitCanonicalPostData<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> extends DevvitJsonObject {
+  readonly mpgd: {
+    readonly schemaVersion: typeof operationSchemaVersion;
+    readonly appScope: string;
+    readonly subredditId: string;
+    readonly operationType: string;
+    readonly operationId: string;
+  };
+  readonly launch: {
+    readonly schemaVersion: typeof operationSchemaVersion;
+    readonly entry: string;
+    readonly params: TLaunchParams;
+  };
+  readonly payload: TPayload;
+}
+export interface DevvitPostOperationDefinition<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
+  readonly operationType: string;
+  readonly parsePayload: (input: unknown) => TPayload;
+  readonly parseLaunchParams: (input: unknown) => TLaunchParams;
+  readonly maxPostDataBytes?: number;
+}
+export interface DevvitPostOperationDescriptorInput<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
+  readonly scope: DevvitPostOperationScope;
+  /** Must be stable across process restarts and retries. */
+  readonly operationId: string;
+  readonly payload: TPayload;
+  readonly launch: DevvitPostLaunch<TLaunchParams>;
+}
+export interface DevvitPostPublishInput<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
+  readonly scope: DevvitPostOperationScope;
+  readonly operationId: string;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+}
+export interface DevvitPostPublishReceipt {
+  readonly postId: string;
+}
+export interface DevvitPostReconciliationCandidate {
+  readonly postId: string;
+  readonly postData: unknown;
+}
+export type DevvitPostReconciliationReason = 'submission-attempted' | 'submit-outcome-unknown' | 'invalid-publish-receipt' | 'receipt-write-failed' | 'match-not-found' | 'invalid-reconciliation-candidate' | 'reconciliation-failed';
+export type DevvitPostOperationResult<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> = {
+  readonly status: 'missing';
+  readonly operationId: string;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'prepared';
+  readonly operationId: string;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'created' | 'existing' | 'recovered';
+  readonly operationId: string;
+  readonly postId: string;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'reconciliation-required';
+  readonly operationId: string;
+  readonly reason: DevvitPostReconciliationReason;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'busy';
+  readonly operationId: string;
+  readonly reason: 'store-contention' | 'reconciliation-lease-held';
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'conflict';
+  readonly operationId: string;
+  readonly reason: 'descriptor-mismatch';
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'terminal-unresolved';
+  readonly operationId: string;
+  readonly reason: 'multiple-exact-matches' | 'published-receipt-conflict';
+  readonly postIds: readonly string[];
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+};
+export interface ExecuteDevvitPostOperationInput<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> extends DevvitPostOperationDescriptorInput<TPayload, TLaunchParams> {
+  readonly publish: (input: DevvitPostPublishInput<TPayload, TLaunchParams>) => Promise<DevvitPostPublishReceipt>;
+}
+export interface ReconcileDevvitPostOperationInput<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> extends DevvitPostOperationDescriptorInput<TPayload, TLaunchParams> {
+  readonly findCandidates: (input: DevvitPostPublishInput<TPayload, TLaunchParams>) => Promise<readonly DevvitPostReconciliationCandidate[]>;
+}
+export interface DevvitPostOperationCoordinator<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
+  execute(input: ExecuteDevvitPostOperationInput<TPayload, TLaunchParams>): Promise<DevvitPostOperationResult<TPayload, TLaunchParams>>;
+  read(input: DevvitPostOperationDescriptorInput<TPayload, TLaunchParams>): Promise<DevvitPostOperationResult<TPayload, TLaunchParams>>;
+  reconcile(input: ReconcileDevvitPostOperationInput<TPayload, TLaunchParams>): Promise<DevvitPostOperationResult<TPayload, TLaunchParams>>;
+}
+export interface CreateDevvitPostOperationCoordinatorOptions<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
+  readonly definition: DevvitPostOperationDefinition<TPayload, TLaunchParams>;
+  readonly store: DevvitDurableOperationStore;
+  readonly now?: () => number;
+  readonly createToken?: () => string;
+  readonly leaseTtlMs?: number;
+  readonly storeAttempts?: number;
+}
+export declare class DevvitPostOperationValidationError extends TypeError {
+  constructor(message: string, options?: ErrorOptions);
+}
+export declare class DevvitPostOperationStateError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+export declare function defineDevvitPostOperation<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject>(definition: DevvitPostOperationDefinition<TPayload, TLaunchParams>): DevvitPostOperationDefinition<TPayload, TLaunchParams>;
+export declare function createDevvitPostOperationCoordinator<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject>(input: CreateDevvitPostOperationCoordinatorOptions<TPayload, TLaunchParams>): DevvitPostOperationCoordinator<TPayload, TLaunchParams>;
+export declare function createDevvitPostOperationKey(input: {
+  readonly scope: DevvitPostOperationScope;
+  readonly operationType: string;
+  readonly operationId: string;
+}): string;
+export {};

package/dist/server/post-operation.js

@@ -0,0 +1,857 @@
+const operationSchemaVersion = 1;
+const defaultLeaseTtlMs = 30000;
+const defaultMaxPostDataBytes = 2048;
+const defaultStoreAttempts = 8;
+const maximumStoreAttempts = 32;
+const maximumIdentifierLength = 128;
+const maximumOperationTypeLength = 64;
+const maximumLeaseTtlMs = 60 * 60 * 1000;
+const operationTypePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const entryPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/u;
+const redditPostIdPattern = /^t3_[A-Za-z0-9]+$/u;
+const redditSubredditIdPattern = /^t5_[a-z0-9]+$/u;
+export class DevvitPostOperationValidationError extends TypeError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'DevvitPostOperationValidationError';
+    }
+}
+export class DevvitPostOperationStateError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'DevvitPostOperationStateError';
+    }
+}
+export function defineDevvitPostOperation(definition) {
+    assertOperationType(definition.operationType);
+    assertPositiveSafeInteger(definition.maxPostDataBytes ?? defaultMaxPostDataBytes, 'maxPostDataBytes');
+    if (typeof definition.parsePayload !== 'function') {
+        throw new DevvitPostOperationValidationError('parsePayload must be a function.');
+    }
+    if (typeof definition.parseLaunchParams !== 'function') {
+        throw new DevvitPostOperationValidationError('parseLaunchParams must be a function.');
+    }
+    return Object.freeze({ ...definition });
+}
+export function createDevvitPostOperationCoordinator(input) {
+    const definition = defineDevvitPostOperation(input.definition);
+    const now = input.now ?? Date.now;
+    const createToken = input.createToken ?? defaultTokenFactory;
+    const leaseTtlMs = input.leaseTtlMs ?? defaultLeaseTtlMs;
+    const storeAttempts = input.storeAttempts ?? defaultStoreAttempts;
+    assertPositiveSafeInteger(leaseTtlMs, 'leaseTtlMs');
+    if (leaseTtlMs > maximumLeaseTtlMs) {
+        throw new DevvitPostOperationValidationError(`leaseTtlMs must not exceed ${String(maximumLeaseTtlMs)}.`);
+    }
+    assertPositiveSafeInteger(storeAttempts, 'storeAttempts');
+    if (storeAttempts > maximumStoreAttempts) {
+        throw new DevvitPostOperationValidationError(`storeAttempts must not exceed ${String(maximumStoreAttempts)}.`);
+    }
+    return {
+        execute,
+        read,
+        reconcile,
+    };
+    async function execute(request) {
+        if (typeof request.publish !== 'function') {
+            throw new DevvitPostOperationValidationError('publish must be a function.');
+        }
+        const descriptor = createDescriptor(definition, request);
+        const operationKey = createDevvitPostOperationKey({
+            scope: request.scope,
+            operationType: definition.operationType,
+            operationId: request.operationId,
+        });
+        for (let attempt = 0; attempt < storeAttempts; attempt += 1) {
+            let current = await readOperation(operationKey, descriptor, definition, input.store);
+            if (current.kind === 'missing') {
+                const timestamp = readTimestamp(now);
+                const prepared = {
+                    schemaVersion: operationSchemaVersion,
+                    revision: 0,
+                    operationKey,
+                    phase: 'prepared',
+                    descriptor,
+                    createdAt: timestamp,
+                    updatedAt: timestamp,
+                };
+                const preparedRaw = serializeRecord(prepared);
+                if (!await input.store.create(operationKey, preparedRaw)) {
+                    continue;
+                }
+                current = { kind: 'record', raw: preparedRaw, record: prepared };
+            }
+            if (current.kind === 'conflict') {
+                return conflictResult(descriptor);
+            }
+            switch (current.record.phase) {
+                case 'prepared': {
+                    const timestamp = Math.max(readTimestamp(now), current.record.updatedAt);
+                    const attempted = {
+                        ...current.record,
+                        revision: current.record.revision + 1,
+                        phase: 'attempted',
+                        attemptId: readToken(createToken, 'submission attempt'),
+                        attemptedAt: timestamp,
+                        updatedAt: timestamp,
+                    };
+                    const attemptedRaw = serializeRecord(attempted);
+                    if (!await input.store.compareAndSet(operationKey, current.raw, attemptedRaw)) {
+                        continue;
+                    }
+                    return submitOnce(attempted, attemptedRaw, request.publish);
+                }
+                case 'attempted':
+                    return reconciliationResult(current.record, 'submission-attempted');
+                case 'published':
+                    return publishedResult(current.record, 'existing');
+                case 'terminal-unresolved':
+                    return terminalResult(current.record);
+            }
+        }
+        return busyResult(descriptor, 'store-contention');
+    }
+    async function read(request) {
+        const descriptor = createDescriptor(definition, request);
+        const operationKey = createDevvitPostOperationKey({
+            scope: request.scope,
+            operationType: definition.operationType,
+            operationId: request.operationId,
+        });
+        const current = await readOperation(operationKey, descriptor, definition, input.store);
+        if (current.kind === 'missing') {
+            return missingResult(descriptor);
+        }
+        if (current.kind === 'conflict') {
+            return conflictResult(descriptor);
+        }
+        switch (current.record.phase) {
+            case 'prepared':
+                return preparedResult(current.record);
+            case 'attempted':
+                return reconciliationResult(current.record, 'submission-attempted');
+            case 'published':
+                return publishedResult(current.record, 'existing');
+            case 'terminal-unresolved':
+                return terminalResult(current.record);
+        }
+    }
+    async function reconcile(request) {
+        if (typeof request.findCandidates !== 'function') {
+            throw new DevvitPostOperationValidationError('findCandidates must be a function.');
+        }
+        const descriptor = createDescriptor(definition, request);
+        const operationKey = createDevvitPostOperationKey({
+            scope: request.scope,
+            operationType: definition.operationType,
+            operationId: request.operationId,
+        });
+        const current = await readOperation(operationKey, descriptor, definition, input.store);
+        if (current.kind === 'missing') {
+            return missingResult(descriptor);
+        }
+        if (current.kind === 'conflict') {
+            return conflictResult(descriptor);
+        }
+        if (current.record.phase === 'prepared') {
+            return preparedResult(current.record);
+        }
+        if (current.record.phase === 'published') {
+            return publishedResult(current.record, 'existing');
+        }
+        if (current.record.phase === 'terminal-unresolved') {
+            return terminalResult(current.record);
+        }
+        const leaseKey = `${operationKey}:reconciliation-lease`;
+        const leaseToken = readToken(createToken, 'reconciliation lease');
+        const leaseExpirationMs = readTimestamp(now) + leaseTtlMs;
+        const leaseExpiration = new Date(leaseExpirationMs);
+        if (!Number.isSafeInteger(leaseExpirationMs) || Number.isNaN(leaseExpiration.getTime())) {
+            throw new DevvitPostOperationValidationError('The reconciliation lease expiration must be a valid timestamp.');
+        }
+        if (!await input.store.createLease(leaseKey, leaseToken, leaseExpiration)) {
+            return busyResult(descriptor, 'reconciliation-lease-held');
+        }
+        try {
+            let candidates;
+            try {
+                candidates = await request.findCandidates(toPublishInput(descriptor));
+            }
+            catch {
+                return reconciliationResult(current.record, 'reconciliation-failed');
+            }
+            if (!Array.isArray(candidates)) {
+                return reconciliationResult(current.record, 'invalid-reconciliation-candidate');
+            }
+            let exactMatches;
+            try {
+                exactMatches = exactReconciliationMatches(candidates, descriptor, definition);
+            }
+            catch (error) {
+                if (error instanceof DevvitPostOperationValidationError) {
+                    return reconciliationResult(current.record, 'invalid-reconciliation-candidate');
+                }
+                throw error;
+            }
+            if (exactMatches.length === 0) {
+                return reconciliationResult(current.record, 'match-not-found');
+            }
+            if (exactMatches.length === 1) {
+                const [match] = exactMatches;
+                if (match === undefined) {
+                    throw new DevvitPostOperationStateError('Expected one reconciliation match.');
+                }
+                return commitPublished(current.record, current.raw, match.postId, true, 'recovered');
+            }
+            return commitTerminal(current.record, current.raw, 'multiple-exact-matches', exactMatches.map((candidate) => candidate.postId));
+        }
+        finally {
+            try {
+                await input.store.releaseLease(leaseKey, leaseToken);
+            }
+            catch {
+                // The fenced lease expires on its own; cleanup must not mask a durable result.
+            }
+        }
+    }
+    async function submitOnce(record, raw, publish) {
+        let receipt;
+        try {
+            receipt = await publish(toPublishInput(record.descriptor));
+        }
+        catch {
+            return reconciliationResult(record, 'submit-outcome-unknown');
+        }
+        if (!isRedditPostId(receipt?.postId)) {
+            return reconciliationResult(record, 'invalid-publish-receipt');
+        }
+        try {
+            return await commitPublished(record, raw, receipt.postId, false, 'created');
+        }
+        catch {
+            return reconciliationResult(record, 'receipt-write-failed');
+        }
+    }
+    async function commitPublished(source, sourceRaw, postId, recovered, successStatus) {
+        let expectedRecord = source;
+        let expectedRaw = sourceRaw;
+        for (let attempt = 0; attempt < storeAttempts; attempt += 1) {
+            const timestamp = Math.max(readTimestamp(now), expectedRecord.updatedAt);
+            const published = {
+                schemaVersion: operationSchemaVersion,
+                revision: expectedRecord.revision + 1,
+                operationKey: expectedRecord.operationKey,
+                phase: 'published',
+                descriptor: expectedRecord.descriptor,
+                createdAt: expectedRecord.createdAt,
+                updatedAt: timestamp,
+                attemptId: source.attemptId,
+                attemptedAt: source.attemptedAt,
+                postId,
+                publishedAt: timestamp,
+                recovered,
+            };
+            if (await input.store.compareAndSet(source.operationKey, expectedRaw, serializeRecord(published))) {
+                return publishedResult(published, successStatus);
+            }
+            const reread = await readOperation(source.operationKey, source.descriptor, definition, input.store);
+            if (reread.kind === 'missing' || reread.kind === 'conflict') {
+                throw new DevvitPostOperationStateError(`Durable post operation changed incompatibly while recording post ${postId}.`);
+            }
+            if (reread.record.phase === 'published') {
+                if (reread.record.postId === postId) {
+                    return publishedResult(reread.record, successStatus);
+                }
+                const conflictingPostIds = [reread.record.postId, postId];
+                return commitTerminal(reread.record, reread.raw, 'published-receipt-conflict', conflictingPostIds);
+            }
+            if (reread.record.phase === 'terminal-unresolved') {
+                return terminalResult(reread.record);
+            }
+            if (reread.record.phase !== 'attempted' || reread.record.attemptId !== source.attemptId) {
+                throw new DevvitPostOperationStateError(`Durable post operation lost its permanent attempt fence for post ${postId}.`);
+            }
+            expectedRecord = reread.record;
+            expectedRaw = reread.raw;
+        }
+        return busyResult(source.descriptor, 'store-contention');
+    }
+    async function commitTerminal(source, sourceRaw, reason, postIds) {
+        const normalizedPostIds = [...new Set(postIds)].sort();
+        if (normalizedPostIds.length < 2) {
+            throw new DevvitPostOperationStateError('A terminal post operation requires at least two distinct post IDs.');
+        }
+        let expectedRecord = source;
+        let expectedRaw = sourceRaw;
+        let expectedPostIds = normalizedPostIds;
+        // One extra convergence attempt preserves ambiguity evidence when the first
+        // CAS loses specifically to an attempted -> published transition.
+        for (let attempt = 0; attempt < storeAttempts + 1; attempt += 1) {
+            const timestamp = Math.max(readTimestamp(now), expectedRecord.updatedAt);
+            const terminal = {
+                schemaVersion: operationSchemaVersion,
+                revision: expectedRecord.revision + 1,
+                operationKey: expectedRecord.operationKey,
+                phase: 'terminal-unresolved',
+                descriptor: expectedRecord.descriptor,
+                createdAt: expectedRecord.createdAt,
+                updatedAt: timestamp,
+                attemptId: expectedRecord.attemptId,
+                attemptedAt: expectedRecord.attemptedAt,
+                reason,
+                postIds: expectedPostIds,
+                unresolvedAt: timestamp,
+            };
+            if (await input.store.compareAndSet(source.operationKey, expectedRaw, serializeRecord(terminal))) {
+                return terminalResult(terminal);
+            }
+            const current = await readOperation(source.operationKey, source.descriptor, definition, input.store);
+            if (current.kind !== 'record') {
+                throw new DevvitPostOperationStateError('Durable post operation changed incompatibly while recording a terminal outcome.');
+            }
+            if (current.record.phase === 'terminal-unresolved') {
+                return terminalResult(current.record);
+            }
+            if (current.record.phase === 'prepared'
+                || current.record.attemptId !== source.attemptId) {
+                throw new DevvitPostOperationStateError('Durable post operation lost its permanent attempt fence while recording a terminal outcome.');
+            }
+            expectedRecord = current.record;
+            expectedRaw = current.raw;
+            if (current.record.phase === 'published') {
+                expectedPostIds = [...new Set([...expectedPostIds, current.record.postId])].sort();
+            }
+        }
+        return busyResult(source.descriptor, 'store-contention');
+    }
+}
+export function createDevvitPostOperationKey(input) {
+    const appScope = assertIdentifier(input.scope.appScope, 'appScope');
+    const subredditId = assertSubredditId(input.scope.subredditId);
+    const operationId = assertIdentifier(input.operationId, 'operationId');
+    assertOperationType(input.operationType);
+    return [
+        'mpgd:devvit:post-operation:v1',
+        encodeKeyComponent(appScope),
+        encodeKeyComponent(subredditId),
+        encodeKeyComponent(input.operationType),
+        encodeKeyComponent(operationId),
+        'state',
+    ].join(':');
+}
+function createDescriptor(definition, input) {
+    const scope = {
+        appScope: assertIdentifier(input.scope.appScope, 'appScope'),
+        subredditId: assertSubredditId(input.scope.subredditId),
+    };
+    const operationId = assertIdentifier(input.operationId, 'operationId');
+    const entry = assertEntry(input.launch.entry);
+    const payload = parseJsonObject(definition.parsePayload, input.payload, 'payload');
+    const params = parseJsonObject(definition.parseLaunchParams, input.launch.params, 'launch.params');
+    const descriptor = {
+        mpgd: {
+            schemaVersion: operationSchemaVersion,
+            appScope: scope.appScope,
+            subredditId: scope.subredditId,
+            operationType: definition.operationType,
+            operationId,
+        },
+        launch: {
+            schemaVersion: operationSchemaVersion,
+            entry,
+            params,
+        },
+        payload,
+    };
+    assertPostDataByteLength(descriptor, definition.maxPostDataBytes ?? defaultMaxPostDataBytes);
+    return freezeJsonValue(descriptor);
+}
+async function readOperation(operationKey, descriptor, definition, store) {
+    const raw = await store.read(operationKey);
+    if (raw === undefined) {
+        return { kind: 'missing' };
+    }
+    const record = parseStoredRecord(raw, operationKey, definition);
+    if (canonicalJson(record.descriptor) !== canonicalJson(descriptor)) {
+        return { kind: 'conflict' };
+    }
+    return { kind: 'record', raw, record };
+}
+function parseStoredRecord(raw, operationKey, definition) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new DevvitPostOperationStateError('Stored Devvit post operation is not valid JSON.', {
+            cause: error,
+        });
+    }
+    try {
+        const record = assertObject(parsed, 'stored operation');
+        const phase = assertString(record.phase, 'stored operation.phase');
+        const commonKeys = [
+            'schemaVersion',
+            'revision',
+            'operationKey',
+            'phase',
+            'descriptor',
+            'createdAt',
+            'updatedAt',
+        ];
+        let phaseKeys;
+        switch (phase) {
+            case 'prepared':
+                phaseKeys = [];
+                break;
+            case 'attempted':
+                phaseKeys = ['attemptId', 'attemptedAt'];
+                break;
+            case 'published':
+                phaseKeys = ['attemptId', 'attemptedAt', 'postId', 'publishedAt', 'recovered'];
+                break;
+            case 'terminal-unresolved':
+                phaseKeys = ['attemptId', 'attemptedAt', 'reason', 'postIds', 'unresolvedAt'];
+                break;
+            default:
+                throw new DevvitPostOperationValidationError(`Unsupported stored operation phase: ${phase}`);
+        }
+        assertExactKeys(record, [...commonKeys, ...phaseKeys], 'stored operation');
+        assertEqual(record.schemaVersion, operationSchemaVersion, 'stored operation.schemaVersion');
+        const revision = assertNonNegativeSafeInteger(record.revision, 'stored operation.revision');
+        assertEqual(record.operationKey, operationKey, 'stored operation.operationKey');
+        const descriptor = parseCanonicalPostData(record.descriptor, definition);
+        const createdAt = assertTimestamp(record.createdAt, 'stored operation.createdAt');
+        const updatedAt = assertTimestamp(record.updatedAt, 'stored operation.updatedAt');
+        if (updatedAt < createdAt) {
+            throw new DevvitPostOperationValidationError('stored operation.updatedAt must not precede createdAt.');
+        }
+        if (phase === 'prepared') {
+            assertEqual(revision, 0, 'prepared operation revision');
+            if (updatedAt !== createdAt) {
+                throw new DevvitPostOperationValidationError('Prepared operation timestamps must be equal.');
+            }
+            return {
+                schemaVersion: operationSchemaVersion,
+                revision,
+                operationKey,
+                phase,
+                descriptor,
+                createdAt,
+                updatedAt,
+            };
+        }
+        const attemptId = assertIdentifier(record.attemptId, 'stored operation.attemptId');
+        const attemptedAt = assertTimestamp(record.attemptedAt, 'stored operation.attemptedAt');
+        if (revision < 1 || attemptedAt < createdAt || updatedAt < attemptedAt) {
+            throw new DevvitPostOperationValidationError('Stored attempt metadata is inconsistent.');
+        }
+        if (phase === 'attempted') {
+            assertEqual(revision, 1, 'attempted operation revision');
+            if (updatedAt !== attemptedAt) {
+                throw new DevvitPostOperationValidationError('Attempted operation timestamps must be equal.');
+            }
+            return {
+                schemaVersion: operationSchemaVersion,
+                revision,
+                operationKey,
+                phase,
+                descriptor,
+                createdAt,
+                updatedAt,
+                attemptId,
+                attemptedAt,
+            };
+        }
+        if (phase === 'published') {
+            assertEqual(revision, 2, 'published operation revision');
+            const postId = assertPostId(record.postId, 'stored operation.postId');
+            const publishedAt = assertTimestamp(record.publishedAt, 'stored operation.publishedAt');
+            const recovered = assertBoolean(record.recovered, 'stored operation.recovered');
+            if (publishedAt < attemptedAt || updatedAt !== publishedAt) {
+                throw new DevvitPostOperationValidationError('Stored publication timestamps are inconsistent.');
+            }
+            return {
+                schemaVersion: operationSchemaVersion,
+                revision,
+                operationKey,
+                phase,
+                descriptor,
+                createdAt,
+                updatedAt,
+                attemptId,
+                attemptedAt,
+                postId,
+                publishedAt,
+                recovered,
+            };
+        }
+        const reason = record.reason;
+        if (reason !== 'multiple-exact-matches' && reason !== 'published-receipt-conflict') {
+            throw new DevvitPostOperationValidationError('Stored terminal reason is not supported.');
+        }
+        if (revision !== 2 && revision !== 3) {
+            throw new DevvitPostOperationValidationError('terminal operation revision must be 2 or 3.');
+        }
+        if (reason === 'published-receipt-conflict' && revision !== 3) {
+            throw new DevvitPostOperationValidationError('A published receipt conflict must follow a published state.');
+        }
+        if (!Array.isArray(record.postIds) || record.postIds.length < 2) {
+            throw new DevvitPostOperationValidationError('Stored terminal operation must contain at least two post IDs.');
+        }
+        const postIds = record.postIds.map((postId, index) => assertPostId(postId, `stored operation.postIds[${String(index)}]`));
+        if (new Set(postIds).size !== postIds.length) {
+            throw new DevvitPostOperationValidationError('Stored terminal post IDs must be unique.');
+        }
+        const unresolvedAt = assertTimestamp(record.unresolvedAt, 'stored operation.unresolvedAt');
+        if (unresolvedAt < attemptedAt || updatedAt !== unresolvedAt) {
+            throw new DevvitPostOperationValidationError('Stored terminal timestamps are inconsistent.');
+        }
+        return {
+            schemaVersion: operationSchemaVersion,
+            revision,
+            operationKey,
+            phase: 'terminal-unresolved',
+            descriptor,
+            createdAt,
+            updatedAt,
+            attemptId,
+            attemptedAt,
+            reason,
+            postIds,
+            unresolvedAt,
+        };
+    }
+    catch (error) {
+        if (error instanceof DevvitPostOperationStateError) {
+            throw error;
+        }
+        throw new DevvitPostOperationStateError('Stored Devvit post operation is invalid.', {
+            cause: error,
+        });
+    }
+}
+function parseCanonicalPostData(input, definition) {
+    const postData = assertObject(input, 'postData');
+    assertExactKeys(postData, ['mpgd', 'launch', 'payload'], 'postData');
+    const marker = assertObject(postData.mpgd, 'postData.mpgd');
+    assertExactKeys(marker, ['schemaVersion', 'appScope', 'subredditId', 'operationType', 'operationId'], 'postData.mpgd');
+    assertEqual(marker.schemaVersion, operationSchemaVersion, 'postData.mpgd.schemaVersion');
+    const operationType = assertString(marker.operationType, 'postData.mpgd.operationType');
+    assertEqual(operationType, definition.operationType, 'postData.mpgd.operationType');
+    const launch = assertObject(postData.launch, 'postData.launch');
+    assertExactKeys(launch, ['schemaVersion', 'entry', 'params'], 'postData.launch');
+    assertEqual(launch.schemaVersion, operationSchemaVersion, 'postData.launch.schemaVersion');
+    const parsed = {
+        mpgd: {
+            schemaVersion: operationSchemaVersion,
+            appScope: assertIdentifier(marker.appScope, 'postData.mpgd.appScope'),
+            subredditId: assertSubredditId(marker.subredditId),
+            operationType,
+            operationId: assertIdentifier(marker.operationId, 'postData.mpgd.operationId'),
+        },
+        launch: {
+            schemaVersion: operationSchemaVersion,
+            entry: assertEntry(launch.entry),
+            params: parseJsonObject(definition.parseLaunchParams, launch.params, 'postData.launch.params'),
+        },
+        payload: parseJsonObject(definition.parsePayload, postData.payload, 'postData.payload'),
+    };
+    assertPostDataByteLength(parsed, definition.maxPostDataBytes ?? defaultMaxPostDataBytes);
+    return freezeJsonValue(parsed);
+}
+function exactReconciliationMatches(candidates, descriptor, definition) {
+    const expected = canonicalJson(descriptor);
+    const exact = new Map();
+    for (const candidate of candidates) {
+        const candidateRecord = assertObject(candidate, 'reconciliation candidate');
+        assertExactKeys(candidateRecord, ['postId', 'postData'], 'reconciliation candidate');
+        const postId = assertPostId(candidateRecord.postId, 'reconciliation candidate.postId');
+        if (!targetsDescriptor(candidateRecord.postData, descriptor)) {
+            continue;
+        }
+        const postData = parseCanonicalPostData(candidateRecord.postData, definition);
+        if (canonicalJson(postData) === expected) {
+            exact.set(postId, { postId, postData });
+        }
+    }
+    return [...exact.values()];
+}
+function targetsDescriptor(input, descriptor) {
+    if (!isPlainObject(input) || !isPlainObject(input.mpgd)) {
+        return false;
+    }
+    const marker = input.mpgd;
+    return marker.schemaVersion === operationSchemaVersion
+        && marker.appScope === descriptor.mpgd.appScope
+        && marker.subredditId === descriptor.mpgd.subredditId
+        && marker.operationType === descriptor.mpgd.operationType
+        && marker.operationId === descriptor.mpgd.operationId;
+}
+function serializeRecord(record) {
+    return canonicalJson(record);
+}
+function canonicalJson(input) {
+    if (input === null || typeof input === 'boolean' || typeof input === 'string') {
+        return JSON.stringify(input);
+    }
+    if (typeof input === 'number') {
+        if (!Number.isFinite(input)) {
+            throw new DevvitPostOperationValidationError('JSON numbers must be finite.');
+        }
+        return JSON.stringify(input);
+    }
+    if (Array.isArray(input)) {
+        return `[${input.map((value) => canonicalJson(value)).join(',')}]`;
+    }
+    const object = input;
+    return `{${Object.keys(object)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)
+        .join(',')}}`;
+}
+function parseJsonObject(parser, input, label) {
+    let parsed;
+    try {
+        parsed = parser(input);
+    }
+    catch (error) {
+        throw new DevvitPostOperationValidationError(`${label} did not pass its parser.`, {
+            cause: error,
+        });
+    }
+    if (!isPlainObject(parsed)) {
+        throw new DevvitPostOperationValidationError(`${label} parser must return a plain object.`);
+    }
+    normalizeJsonValue(parsed, label, new Set());
+    return freezeJsonValue(JSON.parse(canonicalJson(parsed)));
+}
+function freezeJsonValue(input) {
+    if (Array.isArray(input)) {
+        for (const value of input) {
+            freezeJsonValue(value);
+        }
+        return Object.freeze(input);
+    }
+    if (isPlainObject(input)) {
+        for (const value of Object.values(input)) {
+            freezeJsonValue(value);
+        }
+        return Object.freeze(input);
+    }
+    return input;
+}
+function normalizeJsonValue(input, label, ancestors) {
+    if (input === null || typeof input === 'boolean' || typeof input === 'string') {
+        return input;
+    }
+    if (typeof input === 'number') {
+        if (!Number.isFinite(input)) {
+            throw new DevvitPostOperationValidationError(`${label} contains a non-finite number.`);
+        }
+        return input;
+    }
+    if (typeof input !== 'object') {
+        throw new DevvitPostOperationValidationError(`${label} must contain only JSON values.`);
+    }
+    if (ancestors.has(input)) {
+        throw new DevvitPostOperationValidationError(`${label} must not contain cycles.`);
+    }
+    ancestors.add(input);
+    if (Array.isArray(input)) {
+        for (let index = 0; index < input.length; index += 1) {
+            normalizeJsonValue(input[index], `${label}[${String(index)}]`, ancestors);
+        }
+    }
+    else {
+        const prototype = Object.getPrototypeOf(input);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new DevvitPostOperationValidationError(`${label} must use plain JSON objects.`);
+        }
+        for (const [key, value] of Object.entries(input)) {
+            normalizeJsonValue(value, `${label}.${key}`, ancestors);
+        }
+    }
+    ancestors.delete(input);
+    return input;
+}
+function toPublishInput(descriptor) {
+    return Object.freeze({
+        scope: Object.freeze({
+            appScope: descriptor.mpgd.appScope,
+            subredditId: descriptor.mpgd.subredditId,
+        }),
+        operationId: descriptor.mpgd.operationId,
+        postData: descriptor,
+    });
+}
+function missingResult(descriptor) {
+    return { status: 'missing', operationId: descriptor.mpgd.operationId, postData: descriptor };
+}
+function preparedResult(record) {
+    return {
+        status: 'prepared',
+        operationId: record.descriptor.mpgd.operationId,
+        postData: record.descriptor,
+    };
+}
+function publishedResult(record, status) {
+    return {
+        status,
+        operationId: record.descriptor.mpgd.operationId,
+        postId: record.postId,
+        postData: record.descriptor,
+    };
+}
+function reconciliationResult(record, reason) {
+    return {
+        status: 'reconciliation-required',
+        operationId: record.descriptor.mpgd.operationId,
+        reason,
+        postData: record.descriptor,
+    };
+}
+function busyResult(descriptor, reason) {
+    return {
+        status: 'busy',
+        operationId: descriptor.mpgd.operationId,
+        reason,
+        postData: descriptor,
+    };
+}
+function conflictResult(descriptor) {
+    return {
+        status: 'conflict',
+        operationId: descriptor.mpgd.operationId,
+        reason: 'descriptor-mismatch',
+        postData: descriptor,
+    };
+}
+function terminalResult(record) {
+    return {
+        status: 'terminal-unresolved',
+        operationId: record.descriptor.mpgd.operationId,
+        reason: record.reason,
+        postIds: record.postIds,
+        postData: record.descriptor,
+    };
+}
+function assertObject(input, label) {
+    if (!isPlainObject(input)) {
+        throw new DevvitPostOperationValidationError(`${label} must be an object.`);
+    }
+    return input;
+}
+function isPlainObject(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(input);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertExactKeys(input, expectedKeys, label) {
+    const actual = Object.keys(input).sort();
+    const expected = [...expectedKeys].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        throw new DevvitPostOperationValidationError(`${label} has unexpected or missing fields.`);
+    }
+}
+function assertString(input, label) {
+    if (typeof input !== 'string' || input.length === 0) {
+        throw new DevvitPostOperationValidationError(`${label} must be a non-empty string.`);
+    }
+    return input;
+}
+function assertIdentifier(input, label) {
+    const value = assertString(input, label);
+    if (value !== value.trim() || value.length > maximumIdentifierLength) {
+        throw new DevvitPostOperationValidationError(`${label} must be trimmed and at most ${String(maximumIdentifierLength)} characters.`);
+    }
+    return value;
+}
+function assertOperationType(input) {
+    const value = assertString(input, 'operationType');
+    if (value.length > maximumOperationTypeLength || !operationTypePattern.test(value)) {
+        throw new DevvitPostOperationValidationError(`operationType must match ${String(operationTypePattern)} and be at most ${String(maximumOperationTypeLength)} characters.`);
+    }
+}
+function assertEntry(input) {
+    const value = assertIdentifier(input, 'launch.entry');
+    const hasUnsafeSegment = value
+        .split('/')
+        .some((segment) => segment === '' || segment === '.' || segment === '..');
+    if (!entryPattern.test(value) || hasUnsafeSegment) {
+        const requirement = `match ${String(entryPattern)} without empty, dot, or dot-dot segments`;
+        throw new DevvitPostOperationValidationError(`launch.entry must ${requirement}.`);
+    }
+    return value;
+}
+function assertSubredditId(input) {
+    const value = assertIdentifier(input, 'subredditId');
+    if (!redditSubredditIdPattern.test(value)) {
+        throw new DevvitPostOperationValidationError('subredditId must be a canonical lowercase Reddit t5 fullname.');
+    }
+    return value;
+}
+function assertPostId(input, label) {
+    const value = assertString(input, label);
+    if (!isRedditPostId(value)) {
+        throw new DevvitPostOperationValidationError(`${label} must be a Reddit t3 post ID.`);
+    }
+    return value;
+}
+function isRedditPostId(input) {
+    return typeof input === 'string' && redditPostIdPattern.test(input);
+}
+function assertBoolean(input, label) {
+    if (typeof input !== 'boolean') {
+        throw new DevvitPostOperationValidationError(`${label} must be a boolean.`);
+    }
+    return input;
+}
+function assertTimestamp(input, label) {
+    return assertNonNegativeSafeInteger(input, label);
+}
+function assertNonNegativeSafeInteger(input, label) {
+    if (!Number.isSafeInteger(input) || input < 0) {
+        throw new DevvitPostOperationValidationError(`${label} must be a non-negative safe integer.`);
+    }
+    return input;
+}
+function assertPositiveSafeInteger(input, label) {
+    if (!Number.isSafeInteger(input) || input < 1) {
+        throw new DevvitPostOperationValidationError(`${label} must be a positive safe integer.`);
+    }
+}
+function assertEqual(input, expected, label) {
+    if (input !== expected) {
+        throw new DevvitPostOperationValidationError(`${label} does not match the expected value.`);
+    }
+}
+function assertPostDataByteLength(postData, maximumBytes) {
+    const bytes = new TextEncoder().encode(canonicalJson(postData)).byteLength;
+    if (bytes > maximumBytes) {
+        throw new DevvitPostOperationValidationError(`Canonical Devvit post data is ${String(bytes)} bytes; maximum is ${String(maximumBytes)}.`);
+    }
+}
+function encodeKeyComponent(value) {
+    const encoded = encodeURIComponent(value);
+    const byteLength = new TextEncoder().encode(value).byteLength;
+    return `${String(byteLength)}-${encoded}`;
+}
+function readTimestamp(now) {
+    const value = now();
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new DevvitPostOperationValidationError('now must return a non-negative safe integer.');
+    }
+    return value;
+}
+function readToken(createToken, label) {
+    return assertIdentifier(createToken(), label);
+}
+function defaultTokenFactory() {
+    if (typeof globalThis.crypto?.randomUUID !== 'function') {
+        throw new DevvitPostOperationValidationError('Web Crypto randomUUID is required unless createToken is provided.');
+    }
+    return globalThis.crypto.randomUUID();
+}

package/dist/server/redis-post-operation-store.d.ts

@@ -0,0 +1,23 @@
+import type { DevvitDurableOperationStore } from './post-operation.js';
+export interface DevvitRedisSetOptions {
+  readonly nx?: boolean;
+  readonly xx?: boolean;
+  readonly expiration?: Date;
+}
+export interface DevvitRedisTransactionLike {
+  multi(): Promise<void>;
+  discard(): Promise<unknown>;
+  set(key: string, value: string, options?: DevvitRedisSetOptions): Promise<unknown>;
+  del(...keys: readonly string[]): Promise<unknown>;
+  exec(): Promise<readonly unknown[] | null>;
+  unwatch(): Promise<unknown>;
+}
+export interface DevvitRedisLike {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, options?: DevvitRedisSetOptions): Promise<string | undefined | null>;
+  watch(...keys: readonly string[]): Promise<DevvitRedisTransactionLike>;
+}
+export interface DevvitRedisPostOperationStoreOptions {
+  readonly transactionAttempts?: number;
+}
+export declare function createDevvitRedisPostOperationStore(redis: DevvitRedisLike, options?: DevvitRedisPostOperationStoreOptions): DevvitDurableOperationStore;

package/dist/server/redis-post-operation-store.js

@@ -0,0 +1,110 @@
+const defaultTransactionAttempts = 3;
+const maximumTransactionAttempts = 32;
+export function createDevvitRedisPostOperationStore(redis, options = {}) {
+    const transactionAttempts = normalizeTransactionAttempts(options.transactionAttempts);
+    return {
+        read(key) {
+            return redis.get(key);
+        },
+        async create(key, value) {
+            return setIfAbsent(redis, key, value);
+        },
+        async compareAndSet(key, expectedValue, nextValue) {
+            return mutateIfValue({
+                redis,
+                key,
+                expectedValue,
+                transactionAttempts,
+                queueMutation: (transaction) => transaction.set(key, nextValue),
+            });
+        },
+        async createLease(key, token, expiresAt) {
+            assertExpirationDate(expiresAt);
+            return setIfAbsent(redis, key, token, { expiration: expiresAt });
+        },
+        async releaseLease(key, token) {
+            await mutateIfValue({
+                redis,
+                key,
+                expectedValue: token,
+                transactionAttempts,
+                queueMutation: (transaction) => transaction.del(key),
+            });
+        },
+    };
+}
+async function setIfAbsent(redis, key, value, options = {}) {
+    const result = await redis.set(key, value, {
+        ...options,
+        nx: true,
+    });
+    if (result === 'OK') {
+        return true;
+    }
+    // Devvit Redis represents a failed SET NX with an empty/nil response.
+    if (result === '' || result === undefined || result === null) {
+        return false;
+    }
+    throw new Error(`Devvit Redis SET NX returned an unsupported response: ${result}`);
+}
+async function mutateIfValue(input) {
+    for (let attempt = 0; attempt < input.transactionAttempts; attempt += 1) {
+        const transaction = await input.redis.watch(input.key);
+        let multiStarted = false;
+        try {
+            const currentValue = await input.redis.get(input.key);
+            if (currentValue !== input.expectedValue) {
+                await transaction.unwatch();
+                return false;
+            }
+            await transaction.multi();
+            multiStarted = true;
+            await input.queueMutation(transaction);
+            const results = await transaction.exec();
+            if (results === null) {
+                continue;
+            }
+            if (!Array.isArray(results)) {
+                throw new Error('Devvit Redis transaction returned an unsupported response.');
+            }
+            if (results.length > 0) {
+                return true;
+            }
+        }
+        catch (error) {
+            await bestEffortReset(transaction, multiStarted);
+            throw error;
+        }
+    }
+    throw new Error(`Devvit Redis transaction contention exceeded ${String(input.transactionAttempts)} attempts for key: ${input.key}`);
+}
+async function bestEffortReset(transaction, multiStarted) {
+    try {
+        if (multiStarted) {
+            await transaction.discard();
+        }
+        else {
+            await transaction.unwatch();
+        }
+    }
+    catch {
+        // Preserve the original Redis failure; this cleanup is best-effort.
+    }
+}
+function normalizeTransactionAttempts(value) {
+    const transactionAttempts = value ?? defaultTransactionAttempts;
+    if (!Number.isSafeInteger(transactionAttempts)
+        || transactionAttempts < 1
+        || transactionAttempts > maximumTransactionAttempts) {
+        throw new TypeError(`transactionAttempts must be a safe integer from 1 to ${String(maximumTransactionAttempts)}.`);
+    }
+    return transactionAttempts;
+}
+function assertExpirationDate(value) {
+    if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+        throw new TypeError('Devvit Redis lease expiration must be a valid Date.');
+    }
+    if (value.getTime() <= Date.now()) {
+        throw new TypeError('Devvit Redis lease expiration must be in the future.');
+    }
+}

package/dist/surface.d.ts

@@ -0,0 +1,17 @@
+export type DevvitSurfaceMode = 'inline' | 'expanded';
+export type DevvitSurfaceResult = 'inline-preview' | 'expanded-game';
+export interface DevvitSurfaceClient {
+  getWebViewMode(): DevvitSurfaceMode;
+}
+export interface DevvitSurfaceOptions {
+  readonly client: DevvitSurfaceClient;
+  readonly mountInlinePreview: () => void | Promise<void>;
+  readonly loadExpandedGame: () => void | Promise<void>;
+  readonly onModeUnavailable?: (error: unknown) => void;
+}
+/**
+* Starts the light inline surface when Devvit reports inline mode and defers the
+* game bundle until an expanded surface is active. Outside a Devvit host, the
+* expanded game remains available for local browser development.
+*/
+export declare function startDevvitSurface(options: DevvitSurfaceOptions): Promise<DevvitSurfaceResult>;

package/dist/surface.js

@@ -0,0 +1,22 @@
+/**
+ * Starts the light inline surface when Devvit reports inline mode and defers the
+ * game bundle until an expanded surface is active. Outside a Devvit host, the
+ * expanded game remains available for local browser development.
+ */
+export async function startDevvitSurface(options) {
+    let mode;
+    try {
+        mode = options.client.getWebViewMode();
+    }
+    catch (error) {
+        options.onModeUnavailable?.(error);
+        await options.loadExpandedGame();
+        return 'expanded-game';
+    }
+    if (mode === 'inline') {
+        await options.mountInlinePreview();
+        return 'inline-preview';
+    }
+    await options.loadExpandedGame();
+    return 'expanded-game';
+}

package/dist/web.d.ts

@@ -0,0 +1,16 @@
+import type { ShareResult } from '@mpgd/platform';
+import { type DevvitSurfaceOptions, type DevvitSurfaceResult } from './surface.js';
+export type { DevvitSurfaceClient, DevvitSurfaceMode, DevvitSurfaceOptions, DevvitSurfaceResult, } from './surface.js';
+export type DevvitWebSurfaceOptions = Omit<DevvitSurfaceOptions, 'client'>;
+export interface DevvitShareSheetOptions {
+  readonly data?: string;
+  readonly title?: string;
+  readonly text?: string;
+}
+export declare function startDevvitWebSurface(options: DevvitWebSurfaceOptions): Promise<DevvitSurfaceResult>;
+export declare function requestDevvitExpandedMode(event: MouseEvent, entry: string): Promise<void>;
+/**
+* Presents Devvit's native share surface without claiming that the user
+* completed sharing. Devvit does not report a completion callback.
+*/
+export declare function presentDevvitShareSheet(options: DevvitShareSheetOptions): Promise<ShareResult>;

package/dist/web.js

@@ -0,0 +1,41 @@
+import * as devvitWebClient from '@devvit/web/client';
+import { startDevvitSurface, } from './surface.js';
+// The Devvit package publishes browser implementations behind an export
+// condition while its default declaration is a server-side panic module.
+// Keep the narrow browser contract explicit until its default types expose it.
+const browserClient = devvitWebClient;
+export function startDevvitWebSurface(options) {
+    return startDevvitSurface({
+        ...options,
+        client: { getWebViewMode: browserClient.getWebViewMode },
+    });
+}
+export async function requestDevvitExpandedMode(event, entry) {
+    await browserClient.requestExpandedMode(event, entry);
+}
+/**
+ * Presents Devvit's native share surface without claiming that the user
+ * completed sharing. Devvit does not report a completion callback.
+ */
+export async function presentDevvitShareSheet(options) {
+    try {
+        await browserClient.showShareSheet(options);
+        return {
+            status: 'shared',
+            completion: 'presented',
+        };
+    }
+    catch (error) {
+        if (isAbortError(error)) {
+            return { status: 'cancelled' };
+        }
+        return { status: 'unavailable' };
+    }
+}
+function isAbortError(error) {
+    return typeof DOMException !== 'undefined' && error instanceof DOMException
+        ? error.name === 'AbortError'
+        : typeof error === 'object'
+            && error !== null
+            && error.name === 'AbortError';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-devvit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Reddit Devvit Web platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -28,14 +28,27 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./surface": {
+      "types": "./dist/surface.d.ts",
+      "default": "./dist/surface.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "default": "./dist/web.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@mpgd/bridge": "0.5.0",
-    "@mpgd/platform": "0.4.0"
+    "@devvit/web": "0.13.6",
+    "@mpgd/platform": "0.5.0",
+    "@mpgd/bridge": "0.5.0"
   },
   "devDependencies": {
     "ttsc": "0.16.9",
@@ -52,6 +65,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "vitest run"
+    "test": "vitest run && node test/server-dist-import.mjs && node --conditions=browser test/web-dist-import.mjs"
   }
 }