@eigeninteractive/server/testing

@eigeninteractive/server/testing: the test-auth recipe, for the engine's own suite and for implementor test workers alike:

// test/worker.ts, your production entry with explicit Firebase fakes:
export default createEngine({
  ...sameConfig,
  testing: {
    auth: testVerifier(),
    firebaseAdmin: () => testFirebaseAdmin,
  },
});
// a spec:
import { exports } from "cloudflare:workers";
await exports.default.fetch(url, { headers: await testBearer({ uid: "alice" }) });

(exports.default is the loopback binding to the test worker's default export, the supported replacement for the deprecated SELF fetcher. It needs Cloudflare.GlobalProps to declare mainModule; see the engine's own test/env.d.ts for the hand-rolled version, or use wrangler types.)

Tokens are verified through the SAME jose code path production uses; only the JWKS is local. The RS256 keypair below is a public fixture (checked in, shipped in the package); it protects nothing and must never reach a production config: pass testing ONLY in test workers.

Interfaces

FakeCommerceEvidence

Defined in: server/packages/server/src/testing.ts:116

Properties

accountId

accountId: string;

Defined in: server/packages/server/src/testing.ts:119

kind?

optional kind?: "oneTime" | "subscription";

Defined in: server/packages/server/src/testing.ts:124

providerReference

providerReference: string;

Defined in: server/packages/server/src/testing.ts:118

purchasedAt?

optional purchasedAt?: number;

Defined in: server/packages/server/src/testing.ts:121

requiresAcknowledgement?

optional requiresAcknowledgement?: boolean;

Defined in: server/packages/server/src/testing.ts:125

sealedProviderState?

optional sealedProviderState?: string;

Defined in: server/packages/server/src/testing.ts:126

state?

optional state?: CommerceTransactionState;

Defined in: server/packages/server/src/testing.ts:120

transactionId

transactionId: string;

Defined in: server/packages/server/src/testing.ts:117

validFrom?

optional validFrom?: number;

Defined in: server/packages/server/src/testing.ts:122

validUntil?

optional validUntil?: number;

Defined in: server/packages/server/src/testing.ts:123

FakeCommerceProvider

Defined in: server/packages/server/src/testing.ts:136

A fake provider with the controls a lifecycle test needs.

Reconciliation and acknowledgement are the two places where the engine depends on a provider doing something later, so a fake that cannot fail, stall, or refuse to answer cannot prove either of them works.

Extends

CommerceProvider<unknown>

Properties

acknowledged

readonly acknowledged: string[];

Defined in: server/packages/server/src/testing.ts:141

Every transaction this provider was asked to acknowledge, in order.

checkouts

readonly checkouts: {
  accountId: string;
  operationId: string;
  providerReference: string;
  url: string;
}[];

Defined in: server/packages/server/src/testing.ts:151

One entry per checkout session the provider actually opened. A replayed operation identity must not add one.

accountId

accountId: string;

operationId

operationId: string;

providerReference

providerReference: string;

url

url: string;

key

readonly key: string;

Defined in: server/packages/server/src/commerce/types.ts:149

Inherited from

CommerceProvider.key

sweeps

readonly sweeps: string[][];

Defined in: server/packages/server/src/testing.ts:143

Each sweep's requested ids, in order. Proves queue rotation.

transactions

readonly transactions: Map<string, Partial<VerifiedCommerceTransaction>>;

Defined in: server/packages/server/src/testing.ts:139

Current provider truth per transaction, returned by the next sweep. A transaction absent from here is one the provider will not answer for.

Methods

acknowledge()?

optional acknowledge(env, transaction): Promise<void>;

Defined in: server/packages/server/src/commerce/types.ts:157

Runs only after the normalized transaction and grants commit.

Parameters

Parameter	Type
`env`	`unknown`
`transaction`	`CommerceTransactionReference`

Returns

Promise<void>

Inherited from

CommerceProvider.acknowledge

clearFailures()

clearFailures(): void;

Defined in: server/packages/server/src/testing.ts:148

Returns

void

createCheckout()?

optional createCheckout(env, input): Promise<CommerceCheckout>;

Defined in: server/packages/server/src/commerce/types.ts:158

Parameters

Parameter	Type
`env`	`unknown`
`input`	`CreateCheckoutInput`

Returns

Promise<CommerceCheckout>

Inherited from

CommerceProvider.createCheckout

failAcknowledgement()

failAcknowledgement(message?): void;

Defined in: server/packages/server/src/testing.ts:147

Make every acknowledge throw until cleared.

Parameters

Parameter	Type
`message?`	`string`

Returns

void

failNextSweep()

failNextSweep(message?): void;

Defined in: server/packages/server/src/testing.ts:145

Make the whole next reconcile call throw, as a provider outage does.

Parameters

Parameter	Type
`message?`	`string`

Returns

void

management()?

optional management(
   env,
   accountId,
   providerAccountId,
   returnUrl
): Promise<CommerceManagement>;

Defined in: server/packages/server/src/commerce/types.ts:159

Parameters

Parameter	Type
`env`	`unknown`
`accountId`	`string`
`providerAccountId`	`string`
`returnUrl`	`string`

Returns

Promise<CommerceManagement>

Inherited from

CommerceProvider.management

products()?

optional products(env, providerReferences): Promise<readonly CommerceProduct[]>;

Defined in: server/packages/server/src/commerce/types.ts:150

Parameters

Parameter	Type
`env`	`unknown`
`providerReferences`	readonly `string`[]

Returns

Promise<readonly CommerceProduct[]>

Inherited from

CommerceProvider.products

reconcile()?

optional reconcile(env, transactions): Promise<readonly VerifiedCommerceTransaction[]>;

Defined in: server/packages/server/src/commerce/types.ts:155

Fetches current state for locally active or pending transaction refs.

Parameters

Parameter	Type
`env`	`unknown`
`transactions`	readonly `CommerceTransactionReference`[]

Returns

Promise<readonly VerifiedCommerceTransaction[]>

Inherited from

CommerceProvider.reconcile

reportProviderAccount()

reportProviderAccount(providerAccountId): void;

Defined in: server/packages/server/src/testing.ts:154

Report this provider customer on the next checkout instead of the account's usual one, as a provider confusing two customers would.

Parameters

Parameter	Type
`providerAccountId`	`string`

Returns

void

verifyClaim()

verifyClaim(env, input): Promise<VerifiedCommerceTransaction>;

Defined in: server/packages/server/src/commerce/types.ts:151

Parameters

Parameter	Type
`env`	`unknown`
`input`	`VerifyClaimInput`

Returns

Promise<VerifiedCommerceTransaction>

Inherited from

CommerceProvider.verifyClaim

verifyWebhook()?

optional verifyWebhook(env, request): Promise<VerifiedCommerceEvent>;

Defined in: server/packages/server/src/commerce/types.ts:153

Verifies the raw request and fetches current provider state when needed.

Parameters

Parameter	Type
`env`	`unknown`
`request`	`Request`

Properties

anonymous?

optional anonymous?: boolean;

Defined in: server/packages/server/src/testing.ts:75

claims?

optional claims?: Record<string, unknown>;

Defined in: server/packages/server/src/testing.ts:80

Override any registered claim (e.g. an expired exp, a wrong aud).

email?

optional email?: string;

Defined in: server/packages/server/src/testing.ts:76

name?

optional name?: string;

Defined in: server/packages/server/src/testing.ts:77

picture?

optional picture?: string;

Defined in: server/packages/server/src/testing.ts:78

uid

uid: string;

Defined in: server/packages/server/src/testing.ts:74

Variables

TEST_PROJECT_ID

const TEST_PROJECT_ID: "eigen-test" = "eigen-test";

Defined in: server/packages/server/src/testing.ts:39

testFirebaseAdmin

const testFirebaseAdmin: FirebaseAdminEffects;

Defined in: server/packages/server/src/testing.ts:63

No-op Firebase Admin effects for test workers and test Durable Objects.

Functions

fakeCommerceProvider()

function fakeCommerceProvider(
   products,
   now?,
   key?
): FakeCommerceProvider;

Defined in: server/packages/server/src/testing.ts:158

Deterministic provider for commerce lifecycle and implementor conformance tests.

Parameters

Parameter	Type	Default value	Description
`products`	readonly `CommerceProduct` & { `kind?`: `"oneTime"` \| `"subscription"`; }[]	`undefined`	-
`now`	() => `number`	`Date.now`	-
`key`	`string`	`"fake"`	The provider key. Give a sweep test its own, so the reconciliation queue it reasons about holds only the rows that test seeded.

Returns

FakeCommerceProvider

mintTestToken()

function mintTestToken(opts): Promise<string>;

Defined in: server/packages/server/src/testing.ts:83

Parameters

Parameter	Type
`opts`	`TestTokenOptions`

Returns

Promise<string>

testAccount()

function testAccount(
   d1,
   userId,
   now?
): Promise<string>;

Defined in: server/packages/server/src/testing.ts:307

Provision the account a commerce test is about.

The ledger refuses to write for an account that does not exist, because a provider notification names an account from its own metadata and that metadata outlives an erasure. Anything reaching the ledger through the API has already been provisioned by the auth middleware; a test calling the ledger directly has to say so itself.

Parameters

Parameter	Type
`d1`	`D1Database`
`userId`	`string`
`now`	`number`

Returns

Promise<string>

testBearer()

function testBearer(opts): Promise<Record<string, string>>;

Defined in: server/packages/server/src/testing.ts:102

Authorization header for a minted token.

Parameters

Parameter	Type
`opts`	`TestTokenOptions`

Returns

Promise<Record<string, string>>

testMutationHeaders()

function testMutationHeaders(opts): Promise<Record<string, string>>;

Defined in: server/packages/server/src/testing.ts:109

Headers for an authenticated JSON mutation.

Parameters

Parameter	Type
`opts`	`TestTokenOptions`

Returns

Promise<Record<string, string>>

testVerifier()

function testVerifier(): TokenVerifier;

Defined in: server/packages/server/src/testing.ts:69

The verifier a test worker passes under createEngine({ testing }).

Returns

TokenVerifier

withCreationId()

function withCreationId(
   method,
   path,
   body
): unknown;

Defined in: server/packages/server/src/testing.ts:324

Parameters

Parameter	Type
`method`	`string`
`path`	`string`
`body`	`unknown`

Returns

unknown

Interfaces​

FakeCommerceEvidence​

Properties​

accountId​

kind?​

providerReference​

purchasedAt?​

requiresAcknowledgement?​

sealedProviderState?​

state?​

transactionId​

validFrom?​

validUntil?​

FakeCommerceProvider​

Extends​

Properties​

acknowledged​

checkouts​

accountId​

operationId​

providerReference​

url​

key​

Inherited from​

sweeps​

transactions​

Methods​

acknowledge()?​

Parameters​

Returns​

Inherited from​

clearFailures()​

Returns​

createCheckout()?​

Parameters​

Returns​

Inherited from​

failAcknowledgement()​

Parameters​

Returns​

failNextSweep()​

Parameters​

Returns​

management()?​

Parameters​

Returns​

Inherited from​

products()?​

Parameters​

Returns​

Inherited from​

reconcile()?​

Parameters​

Returns​

Inherited from​

reportProviderAccount()​

Parameters​

Returns​

verifyClaim()​

Parameters​

Returns​

Inherited from​

verifyWebhook()?​

Parameters​

Returns​

Inherited from​

TestTokenOptions​

Properties​

anonymous?​

claims?​

email?​

name?​

picture?​

uid​

Variables​

TEST_PROJECT_ID​

testFirebaseAdmin​

Functions​

fakeCommerceProvider()​

Parameters​

Interfaces

FakeCommerceEvidence

Properties

accountId

kind?

providerReference

purchasedAt?

requiresAcknowledgement?

sealedProviderState?

state?

transactionId

validFrom?

validUntil?

FakeCommerceProvider

Extends

Properties

acknowledged

checkouts

accountId

operationId

providerReference

url

key

Inherited from

sweeps

transactions

Methods

acknowledge()?

Parameters

Returns

Inherited from

clearFailures()

Returns

createCheckout()?

Parameters

Returns

Inherited from

failAcknowledgement()

Parameters

Returns

failNextSweep()

Parameters

Returns

management()?

Parameters

Returns

Inherited from

products()?

Parameters

Returns

Inherited from

reconcile()?

Parameters

Returns

Inherited from

reportProviderAccount()

Parameters

Returns

verifyClaim()

Parameters

Returns

Inherited from

verifyWebhook()?

Parameters

Returns

Inherited from

TestTokenOptions

Properties

anonymous?

claims?

email?

name?

picture?

uid

Variables

TEST_PROJECT_ID

testFirebaseAdmin

Functions

fakeCommerceProvider()

Parameters