feat(sdk): expose strict Order and Product types with a typed client

[meem08]

Summary

The SDK previously had no typed surface for reading a merchant's orders and products — consumers had to type indexer API responses themselves, falling back on any or Record<string, unknown>, which defeats TypeScript in the consuming apps. This PR ports the Order/Product shapes to strict TS types in packages/sdk/src/types, adds strict mappers from the indexer's wire rows (themselves decoded from Soroban transfer XDR) into those types, and ships a small AccensaClient whose fetchOrder / listOrders / fetchProduct / listProducts methods all return the strict types.

Closes #126

---

What changed

1. Strict types — packages/sdk/src/types/

• order.ts — Order interface: id (tx hash), productId? (route), amount (decimal string, never a float), asset?, payer?, method?, ledger?, createdAt, and metadata?.
• product.ts — Product interface: id (route path), method?, calls, totalRevenue (decimal string), and metadata?.
• Every column that can be absent on the wire is declared optional (?) with strict null checks: metadata is undefined unless a deployment actually publishes it — never null, never any.
• Available from the package root and via the new @accensa/sdk/types subpath export.

2. Strict mappers — packages/sdk/src/mapping.ts

• orderFromWire / ordersFromResponse and productFromWire / productsFromResponse map the snake-cased JSON the indexer publishes (/api/payments, /api/routes) into Order / Product.
• SQL NULL optional columns are normalised to undefined, and amounts stay strings throughout.
• Single-row mappers return null for unreadable input (matching the defensive style of parseSettlementHeader); the response mappers throw on a malformed row rather than silently dropping it from a page.

3. Typed client — packages/sdk/src/client.ts

• AccensaClient with:
  • listOrders({ limit, cursor }) → OrdersPage (orders, nextCursor) — mirrors GET /api/payments.
  • fetchOrder(txHash) → Order | null — searches the most recent 1000 indexed payments (the API max), documented, since no lookup-by-hash endpoint exists yet.
  • listProducts({ limit, from, to }) → ProductsPage (products, truncated) — mirrors GET /api/routes.
  • fetchProduct(route) → Product | null — searches the top 200 products by revenue, documented.
• AccensaError with the HTTP status is thrown for non-2xx responses; headers lets callers attach whatever credential the deployment requires (the read endpoints are scoped to the signed-in merchant).

4. Wiring

• index.ts re-exports the client, mappers, and types.
• package.json adds the ./types export; tsconfig.json includes src/**/*.ts.

5. Tests & docs

• src/mapping.test.ts — full-row mapping, null → undefined normalisation, required-field validation, malformed-row rejection (15 tests).
• src/client.test.ts — endpoints, query params, header passing, trailing-slash handling, AccensaError on 401, fetchOrder/fetchProduct lookups (14 tests).
• README.md — short "Reading Orders and Products" section with usage.

---

Design notes

• What an "order" is here: one indexed payment — a settled Stellar Asset Contract transfer the indexer decoded from Soroban XDR and recorded in the merchant's ledger. The dashboard's "Recent Orders" widget reads exactly this data (/api/payments).
• What a "product" is here: one of the merchant's sellable x402 endpoints, as the indexer sees it — identity plus aggregated calls / totalRevenue within the reporting window. Price configuration lives in the seller's own routesConfig, which the indexer does not hold, so the SDK types what the API can actually return rather than inventing fields.
• Why optional fields are undefined, not null: strict null checks (metadata?: …) are the acceptance criterion. Mappers convert SQL NULL to undefined, so a consumer never has to handle both.
• Why amounts are strings: the indexer writes money as NUMERIC and serves it as text (amount::text); the SDK preserves that invariant so money never crosses this boundary as a float.

---

Acceptance criteria

Criterion	Status
Consuming the SDK provides full autocomplete for Order and Product fields	✅ Order/Product exported from the root and @accensa/sdk/types, used as the return types of every client method
Strict null checks are enforced on optional fields (e.g. metadata)	✅ optional fields declared ?, mappers normalise null → undefined
SDK builds without TS errors	✅ pnpm typecheck passes for web and SDK

Testing

• pnpm --filter @accensa/sdk test — 6 files, 110 tests passed (29 new).
• pnpm typecheck — web and SDK both clean.
• pnpm exec prettier --check packages/sdk — clean.

[drips-wave]

@meem08 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[vercel]

@meem08 is attempting to deploy a commit to the ACCENSA Team on Vercel.

A member of the Team first needs to authorize it.

[mergekeeper]

MergeKeeper review

Scope: in scope for linked issue #126.
Verdict: clean

The pull request successfully implements strict TypeScript types, mappers, and a typed client for Order and Product in the SDK, fulfilling all issue requirements and acceptance criteria.

Reviewed commit: 2f231b27a2c24b1e04e0457eed9c911e76626446.
CI and merge eligibility are checked separately.

[mergekeeper]

Approved

The pull request successfully implements strict TypeScript types, mappers, and a typed client for Order and Product in the SDK, fulfilling all issue requirements and acceptance criteria.

[mergekeeper]

Merged

Merged with squash.