Troubleshooting

Package cannot be resolved

Confirm that your .npmrc has the @frappes registry configured before install:

@frappes:registry=https://npm.pkg.github.com

If private access is required, ensure your auth token is available in the shell (GITHUB_TOKEN or your org's token variable).

locationId is required for this operation

Some methods require location context (orders, business day, summaries). Provide it once during client creation:

createFirestoreCoreClient({ firestore, tenantId: "tenant_1", locationId: "loc_1" })

Or pass it per call where supported.

Invalid order transition: X -> Y

Order status follows strict transitions:

• new -> accepted -> in_prep -> ready -> completed
• cancelled can be reached from non-terminal states

Use canTransitionOrderStatus(from, to) before writing if you need pre-checks.

Duplicate writes/events

Use idempotencyKey in createOrder, updateOrderStatus, and appendOrderEvent for retry-safe behavior.

Missing transaction behavior

Your Firestore adapter must implement runTransaction and pass transactional getDoc/setDoc/updateDoc to the runner. If this is a no-op, concurrent updates can cause data inconsistencies.