Add upstream error fields and public error contract tests

AGENTS.md

@@ -88,7 +88,7 @@ This repository is a pnpm workspace for the OMS TypeScript SDK. The root package
 ## Commands
 
 - `pnpm install --frozen-lockfile`: Install dependencies in CI-compatible mode.
-- `pnpm check:package-versions`: Verify publishable workspace package versions and SDK peer dependencies stay in sync.
+- `pnpm check:package-versions`: Verify publishable workspace package versions match and connector SDK references use `workspace:*`.
 - `pnpm exec tsc --noEmit`: Typecheck SDK source.
 - `pnpm test`: Run Vitest and type tests.
 - `pnpm test:types`: Compile `type-tests/oidcProviderTypes.ts`; useful for public type/API changes.
@@ -145,10 +145,18 @@ execution commands.
 - Bug fixes should include regression evidence when feasible.
 - For auth, signing, transaction execution, access revocation, storage persistence, and error classification, add focused tests that would fail if the externally visible promise breaks.
 
+### Public Error Contract Tests
+
+- Follow the detailed rules in `TESTING.md` before adding or updating public error contract tests.
+- Exercise real public runtime APIs and mock only external boundaries.
+- Snapshot stable public fields only; do not snapshot raw `cause`, stacks, generated internals, headers, timestamps, or full backend payloads.
+- Snapshot changes are not automatically regressions. First decide whether the new error shape is the intended public contract, then either update the snapshot or fix the implementation.
+
 ## Generated Files and External Artifacts
 
 - `src/generated/waas.gen.ts` is generated by Webrpc and marked `DO NOT EDIT`. Update the generated-client source of truth rather than hand-editing this file as normal source.
 - The generated WaaS header references `schema/waas.ridl`; if regenerating the client, document the schema source and command used.
+- The wagmi connector's SDK peer dependency is intentionally `workspace:*` in source. Release with pnpm so the published package gets the exact SDK version; do not hand-edit that peer to a literal version.
 - `pnpm-lock.yaml` is the dependency lockfile. Update it through pnpm, not by hand.
 - `dist/`, `examples/react/dist/`, `examples/wagmi/dist/`, and `*.tsbuildinfo` files are build outputs and should not be edited as source.
 
@@ -188,6 +196,7 @@ execution commands.
 | Test commands (`package.json` scripts) | `TESTING.md`, `.github/workflows/tests.yml`, `AGENTS.md` Commands section |
 | Node or pnpm version | `.nvmrc`, `package.json#packageManager`, `.github/workflows/*.yml` |
 | New third-party dependency | `package.json`, `pnpm-lock.yaml`, context7 instruction in `AGENTS.md` |
+| Publishable package versioning or workspace peer protocol | `PUBLISHING.md`, `scripts/check-package-versions.cjs`, `pnpm-lock.yaml` |
 | `src/generated/waas.gen.ts` (regenerated) | Document schema source + regen command in PR description |
 | Repo structure (new top-level dirs) | `AGENTS.md` Repository Layout section |
 | Examples added or renamed | `pnpm-workspace.yaml`, root `package.json` scripts, `pages.yml` |

API.md

@@ -774,10 +774,21 @@ class OmsSdkError extends Error {
   status?: number
   txnId?: string
   retryable?: boolean
+  upstreamError?: OmsUpstreamError
   cause?: unknown
 }
 ```
 
+```typescript
+interface OmsUpstreamError {
+  service: 'waas' | 'indexer'
+  name?: string
+  code?: number | string
+  message?: string
+  status?: number
+}
+```
+
 ```typescript
 type OmsSdkErrorCode =
   | 'OMS_HTTP_ERROR'
@@ -789,18 +800,27 @@ type OmsSdkErrorCode =
   | 'OMS_WALLET_SELECTION_STALE'
   | 'OMS_WALLET_SELECTION_UNAVAILABLE'
   | 'OMS_WALLET_SELECTION_IN_FLIGHT'
+  | 'OMS_TRANSACTION_EXECUTION_UNCONFIRMED'
   | 'OMS_TRANSACTION_STATUS_LOOKUP_FAILED'
   | 'OMS_VALIDATION_ERROR'
 ```
 
 `OMS_AUTH_COMMITMENT_CONSUMED` means the OTP/OIDC auth commitment has already been used. Restart the auth flow before retrying.
 
+`OMS_TRANSACTION_EXECUTION_UNCONFIRMED` means transaction preparation succeeded, but the execute request failed before the SDK could confirm whether the transaction was submitted. The error includes `txnId` when available; do not blindly resend the same write solely because the upstream failure looked temporary.
+
+`OMS_TRANSACTION_STATUS_LOOKUP_FAILED` means the transaction was submitted, but post-submit status polling failed. The error includes `txnId` and is retryable by checking status again with `getTransactionStatus`.
+
+`upstreamError` is normalized diagnostic detail from a remote OMS service response or transport failure. Use the SDK-level `code` for application branching; use `upstreamError` for logging and service-specific troubleshooting.
+
+`retryable` describes the failed SDK operation, not the whole user intent. For example, a retryable transaction status lookup failure means retry `getTransactionStatus`; it does not mean blindly resend the original transaction write.
+
 | Class | Typical use |
 |---|---|
 | `OmsSessionError` | Missing, expired, or stale wallet session. |
 | `OmsRequestError` | Network, fetch, or non-2xx HTTP failures. |
 | `OmsResponseError` | Invalid JSON or malformed API responses. |
-| `OmsTransactionError` | Transaction was submitted but status polling failed; includes `txnId`. |
+| `OmsTransactionError` | Transaction execution could not be confirmed or submitted transaction status polling failed; includes `txnId` when available. |
 | `OmsWalletSelectionError` | Manual wallet selection is stale, invalid, or already processing an action. |
 | `OmsValidationError` | SDK-side validation failures before a request is sent. |
 

PUBLISHING.md

@@ -1,18 +1,25 @@
 # Publishing
 
-Publish the SDK before the wagmi connector. The connector has an exact peer dependency on the SDK
-version, so the SDK package must exist in the npm registry first.
+The SDK and wagmi connector release in lockstep. The connector source manifest keeps
+`@0xsequence/typescript-sdk` as `workspace:*` in both `peerDependencies` and `devDependencies`.
+This gives local development a workspace link, and `pnpm pack` / `pnpm publish` rewrites the
+published peer dependency to the exact release version.
 
-Do not use a recursive workspace publish while the connector's peer dependency is intentionally
-lockstep with the SDK version. Publish each package explicitly, in order.
+Do not replace the connector's SDK peer with a literal version in source, and do not publish with
+`npm publish`. Use pnpm from the workspace root so the `workspace:*` protocol is rewritten before
+the package reaches npm.
 
 ## Before Merging The Release PR
 
 Before publishing a new alpha version, update these values to the same exact version:
 
 - `package.json` `version`
 - `packages/oms-wallet-wagmi-connector/package.json` `version`
+
+Leave these values as `workspace:*`:
+
 - `packages/oms-wallet-wagmi-connector/package.json` `peerDependencies["@0xsequence/typescript-sdk"]`
+- `packages/oms-wallet-wagmi-connector/package.json` `devDependencies["@0xsequence/typescript-sdk"]`
 
 ## After The Release PR Is Merged
 
@@ -24,7 +31,7 @@ git pull
 pnpm install --frozen-lockfile
 ```
 
-2. Capture the release version and verify package versions:
+2. Capture the release version and verify package metadata:
 
 ```bash
 VERSION=$(node -p "require('./package.json').version")
@@ -34,53 +41,53 @@ pnpm check:package-versions
 3. Run release checks:
 
 ```bash
-pnpm exec tsc --noEmit
 pnpm test
+pnpm --filter @0xsequence/oms-wallet-wagmi-connector test
 pnpm build
 pnpm build:node-example
 pnpm build:example
 pnpm build:trails-actions-example
-pnpm --filter @0xsequence/oms-wallet-wagmi-connector test
-pnpm --filter @0xsequence/oms-wallet-wagmi-connector build
 pnpm build:wagmi-example
 ```
 
-4. Dry-run the SDK publish:
+4. Dry-run the filtered workspace publish:
 
 ```bash
-pnpm publish --dry-run --no-git-checks --tag alpha --access public
+pnpm --filter @0xsequence/typescript-sdk \
+  --filter @0xsequence/oms-wallet-wagmi-connector \
+  publish --dry-run --no-git-checks --tag alpha --access public
 ```
 
-5. Dry-run the wagmi connector publish:
+If the dry run reports no new packages, the version is already published. Stop and verify the
+intended release version before continuing.
 
-```bash
-pnpm --filter @0xsequence/oms-wallet-wagmi-connector publish --dry-run --no-git-checks --tag alpha --access public
-```
-
-6. Log in to npm if needed:
+5. Log in to npm if needed:
 
 ```bash
 pnpm npm login
 pnpm npm whoami
 ```
 
-7. Publish the SDK:
+6. Publish both workspace packages from the root:
 
 ```bash
-pnpm publish --tag alpha --access public
-pnpm view @0xsequence/typescript-sdk@$VERSION version
+pnpm --filter @0xsequence/typescript-sdk \
+  --filter @0xsequence/oms-wallet-wagmi-connector \
+  publish --tag alpha --access public
 ```
 
-8. Publish the wagmi connector:
+If the filtered publish is interrupted after the SDK is published, rerun the connector publish with
+pnpm:
 
 ```bash
 pnpm --filter @0xsequence/oms-wallet-wagmi-connector publish --tag alpha --access public
-pnpm view @0xsequence/oms-wallet-wagmi-connector@$VERSION version
 ```
 
-9. Verify the alpha dist tags:
+7. Verify published versions and alpha dist tags:
 
 ```bash
+pnpm view @0xsequence/typescript-sdk@$VERSION version
+pnpm view @0xsequence/oms-wallet-wagmi-connector@$VERSION version
 pnpm view @0xsequence/typescript-sdk@alpha version
 pnpm view @0xsequence/oms-wallet-wagmi-connector@alpha version
 ```

README.md

@@ -255,6 +255,24 @@ To end the session, call:
 await oms.wallet.signOut()
 ```
 
+## Errors
+
+Public methods throw `OmsSdkError` subclasses with stable SDK fields such as `code`, `operation`, `status`, and `retryable`. When a failure comes from a remote OMS service response or transport failure, the error also includes `upstreamError` with normalized WaaS or indexer details for logging and service-specific troubleshooting. Application logic should usually branch on the SDK-level `code`.
+
+For transaction writes, `OMS_TRANSACTION_EXECUTION_UNCONFIRMED` means the SDK has a `txnId` from preparation, but the execute request failed before the SDK could confirm whether the transaction was submitted; do not blindly resend the same write. `OMS_TRANSACTION_STATUS_LOOKUP_FAILED` means the transaction was submitted but status polling failed, so retry status lookup with the returned `txnId`. `retryable` describes the failed SDK operation, not the whole user intent.
+
+```typescript
+import { OmsSdkError } from '@0xsequence/typescript-sdk'
+
+try {
+  await oms.wallet.startEmailAuth({ email: 'user@example.com' })
+} catch (err) {
+  if (err instanceof OmsSdkError) {
+    console.log(err.code, err.operation, err.upstreamError)
+  }
+}
+```
+
 ## Networks
 
 The SDK exports `Networks`, `supportedNetworks`, `findNetworkById(id)`, and `findNetworkByName(name)` for the networks currently configured by OMS. Each network has `id`, `name`, `nativeTokenSymbol`, `explorerUrl`, and `displayName`. `name` is the registry/routing slug, while `displayName` is the user-facing label.

TESTING.md

@@ -51,6 +51,34 @@ How testing works in this repo. `AGENTS.md` points here so agents know how to ve
 - Integration tests that need `OMS_PROJECT_ACCESS_KEY` are gated behind the CI secret; they
   may be skipped locally when the env var is absent
 
+### Public error contract tests
+
+- Use `docs/error-contracts.md` as the audit matrix for public SDK/connector error surfaces,
+  recovery semantics, `upstreamError` expectations, and owning tests.
+- Exercise real public runtime APIs such as `oms.wallet.*`, `oms.indexer.*`, exported storage
+  managers, signers, or wagmi connector/provider methods.
+- Do not snapshot manually constructed `OmsSdkError` subclasses unless the error class or helper
+  is the unit under test.
+- Mock only external boundaries: `fetch`, browser globals, storage availability, signer behavior,
+  timers, or backend responses.
+- Snapshot only stable public fields: `name`, `code`, `operation`, `message`, `status`,
+  `retryable`, `txnId`, and `upstreamError`.
+- Do not snapshot `stack`, raw `cause`, generated WebRPC internals, request headers, timestamps,
+  or full backend payloads.
+- Keep backend/upstream mapping tests representative rather than exhaustive per method; cover
+  each transport family through real public calls.
+- Include `upstreamError` only when the tested path truthfully crosses a remote service or
+  transport boundary; SDK-local failures should assert no `upstreamError`.
+- Snapshot changes are not automatically regressions. Decide whether the new error shape is the
+  intended public contract: if correct, update the snapshot and any related docs/type tests; if
+  accidental, fix the implementation. Never update snapshots blindly.
+- Treat `code` and `operation` as stronger contract fields than `message`. Message changes are
+  allowed when intentional, but they should be reviewed as user-visible API/UX changes.
+- `upstreamError` is normalized diagnostic detail from a remote OMS service response or transport
+  failure. Application logic should usually branch on the SDK-level `code`.
+- `retryable` describes the failed SDK operation, not the whole user intent. A retryable status
+  lookup failure does not mean a transaction write should be blindly resent.
+
 ## Execution summary
 
 | Goal | Command |