release: 1.9.0

[stainless-app]

Automated Release PR

1.9.0 (2026-06-05)

Full Changelog: v1.8.0...v1.9.0

Features

• Add encrypted OTP flow (948a93b)
• api: add CNY_ACCOUNT support to external accounts and payment instructions (2a4c89d)
• api: add ID_TYPE and ID_NUMBER to CustomerInfoFieldName enum (51b3b49)
• api: add receiptDeliveryConfirmedAt to transaction responses (c6d1dba)
• api: add SWIFT account type, update COP/EGP account requirements (23edde7)
• api: manual updates (bcb7d4c)
• api: manual updates (605f969)
• api: manual updates (96b093a)
• api: manual updates (3e10796)
• transfers: allow selecting payment rail on transfer-out destination (11e1ce3)

Bug Fixes

• types: require bankName field in BDT/COP/EGP/GHS/PKR external account types (f9c3f11)

Documentation

• api: add KYB requirements to verifications submit method (8cac5e8)
• types: document passkey assertion in auth credentials (4bbc90c)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

[stainless-app]

🧪 Testing

To try out this version of the SDK:

npm install 'https://pkg.stainless.com/s/grid-typescript/2a4c89d2b685fc1ceb4601583f777d337951d549/dist.tar.gz'

Expires at: Sun, 05 Jul 2026 01:39:47 GMT
Updated at: Fri, 05 Jun 2026 01:39:47 GMT

[greptile-apps]

Greptile Summary

This is the automated Stainless-generated 1.9.0 release PR, adding an encrypted OTP two-leg authentication flow (HPKE end-to-end, no plaintext OTP on the wire), CNY_ACCOUNT and SWIFT account-type support, paymentRail selection on transfer-out destinations, and a suite of type/naming refactors across the SDK surface.

• Encrypted OTP flow: POST /auth/credentials/{id}/verify now supports a two-leg signed-retry path for EMAIL_OTP credentials; clients HPKE-encrypt the OTP under an otpEncryptionTargetBundle, receive a 202 with a verificationToken to sign with their ephemeral TEK keypair, then complete with a Grid-Wallet-Signature header.
• Account-type expansion: bankName promoted to required on BDT/COP/GHS/PKR accounts; EgpAccountInfo drops accountNumber (previously required) and swiftCode in favour of phoneNumber; CnyAccount variant added; paymentRail field added to transfer-out destination.
• Type renames across the public API: CryptoEstimateWithdrawalFeeResponse, CustomerListResponsesDefaultPagination, PlatformListInternalAccountsResponse, CardsDefaultPagination, and others were renamed — these are breaking TypeScript changes in a minor-version bump.

Confidence Score: 3/5

This PR ships multiple breaking TypeScript contract changes (field removals, method renames, type renames) under a minor version bump; callers on 1.8.x will encounter compile errors or silent runtime misses on upgrade.

Beyond the breaking changes already flagged in earlier review rounds, this pass found two additional concrete breaks: CryptoEstimateWithdrawalFeeResponse is gone from the public namespace and EgpAccountInfo.accountNumber (previously required) has been removed along with swiftCode. The cumulative pattern of required fields silently dropped or renamed across several resources in a non-major release raises the risk of silent runtime failures for existing consumers.

src/resources/customers/customers.ts, src/resources/platform/external-accounts.ts, src/resources/shared.ts, src/resources/auth/sessions.ts, and src/resources/crypto.ts carry the most impactful breaking changes.

Important Files Changed

Filename	Overview
src/resources/auth/credentials.ts	Adds encrypted OTP two-leg flow: new Grid-Wallet-Signature header param on verify, AuthCredentialChallengeRequest type, expanded AuthMethodResponse carrying otpEncryptionTargetBundle, and documentation updates throughout.
src/resources/auth/sessions.ts	Breaking: SessionRefreshParams.clientPublicKey (top-level body field) is now wrapped inside AuthSessionRefreshRequest; callers passing the old flat shape will silently send an empty body (previously flagged).
src/resources/customers/customers.ts	Multiple breaking changes: generateKYCLink renamed to createKYCLink with a wrapped KycLinkCreateRequest param, CustomerOneovesDefaultPagination typo, response types unified to CustomerOneOf, and CustomerUpdateInternalAccountParams body-wrapping that silently drops old flat params (all previously flagged).
src/resources/crypto.ts	Breaking rename: CryptoEstimateWithdrawalFeeResponse replaced by EstimateCryptoWithdrawalFeeResponse; new EstimateCryptoWithdrawalFeeRequest type added.
src/resources/platform/external-accounts.ts	Breaking: EgpAccountInfo.accountNumber (previously required) removed; swiftCode removed and replaced by phoneNumber; bankName promoted to required on BDT/COP/GHS/PKR account infos; new PlatformExternalAccountCreateRequest and CnyAccount support added.
src/resources/shared.ts	BusinessInfoUpdate interface removed entirely; BusinessCustomer and IndividualCustomer now extend a new Customer base; EgpExternalAccountCreateInfo.accountNumber required field removed; EgpBeneficiary fields widened from required to optional.
src/resources/transfer-out.ts	Adds optional paymentRail field to TransferOutCreateParams.Destination; destination type changed from ExternalAccountReference to a local Destination interface — backwards-compatible since paymentRail is optional.
src/resources/customers/external-accounts.ts	New CnyAccount variant added to ExternalAccountInfoOneOf; bankName promoted to required on BDT/COP/GHS/PKR doc-comment fields; new ExternalAccountListResponse type added.
src/resources/verifications.ts	VerificationListResponse repurposed as a paginated wrapper while the old single-record shape moved to a new Verification type — breaking for TypeScript consumers who referenced the old type shape (previously flagged).

Sequence Diagram

sequenceDiagram
    participant Client
    participant Grid API
    participant Enclave

    Note over Client,Grid API: EMAIL_OTP Encrypted Flow (new in 1.9.0)

    Client->>Grid API: POST /auth/credentials/{id}/challenge
    Grid API-->>Client: AuthMethodResponse (otpEncryptionTargetBundle)

    Note over Client: Generate ephemeral P-256 TEK keypair
    Note over Client: HPKE-encrypt {otp_code, public_key} under bundle

    Client->>Enclave: OTP delivered out-of-band (email)
    Enclave-->>Client: magic OTP (sandbox) / real OTP (production)

    Client->>Grid API: POST /auth/credentials/{id}/verify (encryptedOtpBundle)
    Grid API-->>Client: 202 AuthSignedRequestChallenge (payloadToSign)

    Note over Client: Sign payloadToSign with TEK private key

    Client->>Grid API: POST /auth/credentials/{id}/verify (retry + Grid-Wallet-Signature)
    Grid API-->>Client: 200 AuthSession

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
src/resources/crypto.ts:133-140
**Breaking public type rename in a minor release**

`CryptoEstimateWithdrawalFeeResponse` has been removed from the public namespace and replaced with `EstimateCryptoWithdrawalFeeResponse`. Any TypeScript consumer that imported or referenced the old name directly — e.g., `import type { CryptoEstimateWithdrawalFeeResponse } from '@lightspark/grid-js-sdk'` — will get a compile error after upgrading to 1.9.0. The type is re-exported from `src/resources/index.ts`, so it is a visible breaking change in the public contract.

### Issue 2 of 2
src/resources/platform/external-accounts.ts:288-307
**Breaking field removals on `EgpAccountInfo` in a minor release**

Two fields were removed from `EgpAccountInfo` (and the parallel `EgpExternalAccountCreateInfo` in `shared.ts`): the previously-required `accountNumber: string` is gone entirely, and the optional `swiftCode?: string` is replaced by `phoneNumber?: string`. Any existing TypeScript caller constructing an EGP external account that passed `accountNumber` will now get a compile error ("Object literal may only specify known properties"). Callers that relied on `swiftCode` will silently lose that field with no error. `paymentRails` was also widened from `Array<'BANK_TRANSFER'>` to `Array<'BANK_TRANSFER' | 'MOBILE_MONEY'>`, which is additive, but together these are breaking structural changes in a minor version.

_{Reviews (6): Last reviewed commit: "release: 1.9.0" | Re-trigger Greptile}

[greptile-apps]

Breaking rename from generateKYCLink to createKYCLink in a minor (1.8.0 → 1.9.0) release. Existing callers invoking client.customers.generateKYCLink(...) will get a runtime TypeError: client.customers.generateKYCLink is not a function. The parameter shape also changed: redirectUri is no longer a flat body field but is now nested inside KycLinkCreateRequest, so any caller passing the old shape will silently send a missing body.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/resources/customers/customers.ts
Line: 242

Comment:
Breaking rename from `generateKYCLink` to `createKYCLink` in a minor (1.8.0 → 1.9.0) release. Existing callers invoking `client.customers.generateKYCLink(...)` will get a runtime `TypeError: client.customers.generateKYCLink is not a function`. The parameter shape also changed: `redirectUri` is no longer a flat body field but is now nested inside `KycLinkCreateRequest`, so any caller passing the old shape will silently send a missing body.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

The refund field type on OutgoingTransaction was changed from the locally-defined OutgoingTransaction.Refund namespace type to SimulateAPI.Refund (imported from the sandbox cards simulate module). Any consumers type-checking against the old OutgoingTransaction.Refund path will get a TS compile error. More surprisingly, a production OutgoingTransaction object now references a type defined inside the sandbox package sub-tree, which may feel semantically incorrect to readers of the API surface.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/resources/transactions.ts
Line: 383

Comment:
The `refund` field type on `OutgoingTransaction` was changed from the locally-defined `OutgoingTransaction.Refund` namespace type to `SimulateAPI.Refund` (imported from the sandbox cards simulate module). Any consumers type-checking against the old `OutgoingTransaction.Refund` path will get a TS compile error. More surprisingly, a production `OutgoingTransaction` object now references a type defined inside the `sandbox` package sub-tree, which may feel semantically incorrect to readers of the API surface.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

VerificationListResponse repurposed with an incompatible shape

VerificationListResponse previously described a single verification record (id, createdAt, customerId, errors, verificationStatus, updatedAt). It was the item type iterated over by the list() method. In this PR it is redefined as a paginated wrapper (data: Array<Verification>, hasMore, nextCursor, totalCount) while the list() method now yields Verification items directly.

Any TypeScript consumer that referenced Verifications.VerificationListResponse as the shape of a single verification will get a compile error because the fields no longer exist. Additionally, the new type is never returned by any method on Verifications, making it a semantic orphan in the public namespace.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/resources/verifications.ts
Line: 157-175

Comment:
**`VerificationListResponse` repurposed with an incompatible shape**

`VerificationListResponse` previously described a single verification record (`id`, `createdAt`, `customerId`, `errors`, `verificationStatus`, `updatedAt`). It was the item type iterated over by the `list()` method. In this PR it is redefined as a paginated wrapper (`data: Array<Verification>`, `hasMore`, `nextCursor`, `totalCount`) while the `list()` method now yields `Verification` items directly.

Any TypeScript consumer that referenced `Verifications.VerificationListResponse` as the shape of a single verification will get a compile error because the fields no longer exist. Additionally, the new type is never returned by any method on `Verifications`, making it a semantic orphan in the public namespace.

How can I resolve this? If you propose a fix, please make it concise.