@riseworks/riseworks-sdk 1.0.4

package/ai-skills/references/TYPES.md

@@ -0,0 +1,190 @@
+# Rise SDK — TypeScript types reference
+
+Use this when implementing typed integrations. All types are exported from `riseworks-sdk`.
+
+## Webhook event types
+
+Import for **validated webhook payloads** and **event-type narrowing**:
+
+```ts
+import type {
+  RiseWebhookEvent,
+  PaymentSentV2,
+  PaymentGroupCreatedV2,
+  DepositReceivedV2,
+  InviteAcceptedV2,
+  WithdrawAccountDuplicatedDetectedV2,
+} from 'riseworks-sdk'
+```
+
+- **`RiseWebhookEvent`** — Union of all supported webhook events. Use as the type for `validator.validateEvent()` / `validateEventSafe().event`.
+- **Event-specific types** — Each event payload has a type (e.g. `PaymentSentV2`). Every event includes the base envelope: `object`, `created`, `request_id`, `event_type`, `event_version`, `idempotency_key`.
+
+**Narrow by `event_type` in handlers:**
+
+```ts
+if (event.event_type === 'payment.sent') {
+  // event is PaymentSentV2; event.payment is available
+  const payment = event.payment
+}
+if (event.event_type === 'deposit.received') {
+  // event is DepositReceivedV2; event.deposit is available
+}
+```
+
+**Common event_type values**: `payment.sent`, `payment.group.created`, `deposit.received`, `invite.accepted`, `withdraw_account.duplicated_detected`. Use these same strings in `events` when registering webhooks. Full list: B2B docs Webhooks → Event Types.
+
+## Webhook management types
+
+For **register, list, update, test, delivery history** (from codegen):
+
+```ts
+import type {
+  RegisterWebhookRequest,
+  UpdateWebhookRequest,
+  ListWebhooksRequest,
+  ListWebhooksResponse,
+  GetWebhookResponse,
+  TestWebhookRequest,
+  TestWebhookResponse,
+  DeliveryHistoryResponse,
+  WebhookListItem,
+  DeliveryHistoryItem,
+  WebhookEndpointNanoid,
+  WebhookDeliveryNanoid,
+} from 'riseworks-sdk'
+```
+
+- **`RegisterWebhookRequest`** — `company_nanoid`, `url`, `events` (array of event type strings), `secret` (min 16 chars), optional `team_nanoid`, `name`, `description`, `is_active`.
+- **`ListWebhooksResponse`** — `data.webhooks`, `data.next_cursor`.
+- **`DeliveryHistoryItem`** — `delivery_nanoid`, `event_nanoid`, `status` ('queued' | 'success' | 'failed' | 'retrying'), `response_code`, `created_at`.
+
+## API call types
+
+The SDK also exports request and response types for API calls. Use them for typed params, payloads, and responses instead of hand-written object shapes.
+
+```ts
+import type {
+  RiseApiClientOptions,
+  RiseEnvironment,
+  RiseIdAuthConfig,
+  TeamParams,
+  TeamUserParams,
+  CreateTeamRequest,
+  UpdateTeamRequest,
+  PostTeamResponse,
+  GetTeamResponse,
+  GetTeamUsersResponse,
+  GetTeamSettingsResponse,
+  UpdateTeamSettingsRequest,
+  GetBalanceRequest,
+  GetBalanceResponse,
+  CreatePaymentsRequest,
+  ExecutePaymentsRequest,
+  ExecutePaymentsResponse,
+  CreateExternalRecipientRequest,
+  CreateInstantExternalPaymentRequest,
+  CreateInstantExternalPaymentResponse,
+  PostManagerInvitesRequest,
+  PostManagerInvitesResponse,
+} from 'riseworks-sdk'
+```
+
+- **Auth/config**: `RiseApiClientOptions`, `RiseEnvironment`, `RiseIdAuthConfig`.
+- **Teams**: `TeamParams`, `TeamUserParams`, `CreateTeamRequest`, `UpdateTeamRequest`, `PostTeamResponse`, `GetTeamResponse`, `GetTeamUsersResponse`.
+- **Balances**: `GetBalanceRequest`, `GetBalanceResponse`.
+- **Payments**: `CreatePaymentsRequest`, `ExecutePaymentsRequest`, `ExecutePaymentsResponse`.
+- **Bill pay**: `CreateExternalRecipientRequest`, `CreateInstantExternalPaymentRequest`, `CreateInstantExternalPaymentResponse`.
+- **Invites**: `PostManagerInvitesRequest`, `PostManagerInvitesResponse`.
+
+## Method-to-type mapping
+
+Use these pairings when generating typed SDK code:
+
+- `new RiseApiClient(config)` → `RiseApiClientOptions`
+- `client.teams.create(data)` → `CreateTeamRequest` / `PostTeamResponse`
+- `client.teams.get(params)` → `TeamParams` / `GetTeamResponse`
+- `client.teams.getUsers(params)` → `TeamParams` / `GetTeamUsersResponse`
+- `client.teams.getSettings(params)` → `TeamParams` / `GetTeamSettingsResponse`
+- `client.teams.updateSettings(params, data)` → `TeamParams` / `UpdateTeamSettingsRequest`
+- `client.entityBalance.get(params)` → `GetBalanceRequest` / `GetBalanceResponse`
+- `client.payments.get(params)` → `GetPaymentsRequest` / `GetPaymentsResponse`
+- `client.payments.getPaymentTypedData(data)` → `CreatePaymentsRequest` / `CreatePaymentsResponse`
+- `client.payments.executePaymentWithSignedData(data)` → `ExecutePaymentsRequest` / `ExecutePaymentsResponse`
+- `client.billPay.createRecipient(params, data)` → `ExternalRecipientsParams` / `CreateExternalRecipientRequest`
+- `client.billPay.prepareInstantPayment(data)` → `CreateInstantExternalPaymentRequest` / `CreateInstantExternalPaymentResponse`
+- `client.billPay.executeInstantPayment(data)` → `ExecuteInstantExternalPaymentRequest` / `ExecuteInstantExternalPaymentResponse`
+- `client.invites.get(params)` → `GetInvitesRequest` / `GetInvitesResponse`
+- `client.invites.sendManagerInvite(data)` or manual typed-data flow → `PostManagerInvitesRequest` / `PostManagerInvitesResponse`
+- `client.webhooks.register(data)` → `RegisterWebhookRequest` / `RegisterWebhookResponse`
+- `client.webhooks.list(params)` → `ListWebhooksRequest` / `ListWebhooksResponse`
+- `client.webhooks.test(webhookNanoid, data)` → `TestWebhookRequest` / `TestWebhookResponse`
+
+Example:
+
+```ts
+import { RiseApiClient } from 'riseworks-sdk'
+import type {
+  CreatePaymentsRequest,
+  ExecutePaymentsResponse,
+  GetBalanceRequest,
+} from 'riseworks-sdk'
+
+const payment: CreatePaymentsRequest = {
+  from: teamNanoid,
+  to: [{ to: userNanoid, amount_cents: 10000, currency_symbol: 'USD' }],
+  pay_now: true,
+  network: 'arbitrum',
+}
+
+const balanceParams: GetBalanceRequest = { nanoid: teamNanoid }
+const balance = await client.entityBalance.get(balanceParams)
+const sent: ExecutePaymentsResponse = await client.payments.sendPayment(payment)
+```
+
+## Webhook validator types
+
+```ts
+import {
+  WebhookValidator,
+  WebhookValidationError,
+} from 'riseworks-sdk'
+import type { WebhookValidationResult, WebhookValidationOptions } from 'riseworks-sdk'
+```
+
+- **`WebhookValidator`** — `new WebhookValidator(secret, options?)`. Methods: `validateEvent(body, signature)` returns `RiseWebhookEvent` (throws); `validateEventSafe(body, signature)` returns `WebhookValidationResult`.
+- **`WebhookValidationResult`** — `{ isValid, event?, error?, timestampValid? }`.
+
+## Branded ID types (nanoids)
+
+Use for params and response fields to get correct typing:
+
+```ts
+import type {
+  CompanyNanoid,
+  TeamNanoid,
+  UserNanoid,
+  WithdrawAccountNanoid,
+  WebhookEndpointNanoid,
+  WebhookDeliveryNanoid,
+  InviteNanoid,
+  TransactionNanoid,
+} from 'riseworks-sdk'
+```
+
+- Nanoids are 15-char strings with prefixes: `co-`, `te-`, `us-`, `wa-`, `wh-`, `wl-`, `in-`, `tx-`, etc. Use these types in function args and when reading API responses.
+
+## API response shape
+
+All SDK client methods that return data follow:
+
+- `{ data, success }` — use `response.data` for the payload. Type the `data` field from the method’s return type when possible.
+
+## Amounts and formats
+
+- **Payment amounts**: `amount_cents` (number) for fiat; blockchain amounts often as **strings** (smallest units) to avoid precision loss.
+- **Dates**: ISO-8601 strings or `Date` where the SDK accepts them (e.g. `payments.get()`).
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Event payloads, field specs, and full event list are in the Webhooks section.

package/ai-skills/rise-auth-and-setup/README.md

@@ -0,0 +1,14 @@
+# Rise Auth And Setup Skill
+
+Human-facing notes for the `rise-auth-and-setup` skill.
+
+## Purpose
+
+This skill helps agents initialize `RiseApiClient` correctly and choose between
+JWT auth and `riseIdAuth`.
+
+## Extra references
+
+- `../references/TYPES.md` — config and request/response typing
+- `../references/API_WORKFLOWS.md` — what to do after initialization
+- `references/SETUP_PATTERNS.md` — defaults for environment and auth selection

package/ai-skills/rise-auth-and-setup/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: rise-auth-and-setup
+description: Configures riseworks-sdk authentication, environments, and secure server-side setup. Use when the user mentions setup, configuration, jwtToken, riseIdAuth, SIWE, private keys, environments, or initializing RiseApiClient.
+compatibility: Node.js, TypeScript or JavaScript. Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise Auth And Setup
+
+**Note:** Always read the installed `riseworks-sdk` source when implementing—the SDK may have new functions or types not yet reflected in this skill.
+
+## Default setup choices
+
+- Use `jwtToken` when the application already has a valid JWT.
+- Use `riseIdAuth` when the application needs SDK-managed SIWE-based authentication and refresh.
+- Keep private keys and Rise IDs server-side.
+- Prefer environment variables for secrets.
+- Default to `riseIdAuth` for flows that include automatic signing (`sendPayment`, `sendManagerInvite`, `sendInstantPayment`).
+- Default to `jwtToken` for read-heavy or manual typed-data flows.
+
+## Required setup surface
+
+- `new RiseApiClient({ environment, jwtToken })`
+- `new RiseApiClient({ environment, riseIdAuth: { riseId, privateKey } })`
+
+## Types
+
+- Use `RiseApiClientOptions` for client configuration objects.
+- Use `RiseEnvironment` for environment values and `RiseIdAuthConfig` for `riseIdAuth`.
+- Prefer typed config examples over inline anonymous object shapes.
+
+## API support guidance
+
+- After initialization, prefer a quick verification call such as `client.me.get()`.
+- If the next workflow needs entity context, follow with `client.user.getTeams()` or `client.user.getOrganizations()`.
+- Mention that most other B2B API calls are performed through `RiseApiClient` methods, not raw HTTP calls.
+
+For common SDK API flows after auth, see [references/API_WORKFLOWS.md](../references/API_WORKFLOWS.md).
+For setup defaults and auth-mode selection, see [references/SETUP_PATTERNS.md](references/SETUP_PATTERNS.md).
+
+## Environments
+
+- Use the requested environment explicitly.
+- If the user does not specify one, ask whether they want `dev`, `stg`, or `prod`.
+- Only use a custom `baseUrl` when the user clearly needs it.
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Authentication, Understanding Private Keys, Secondary Wallets, SDK Configuration. Suggest when the user needs SIWE details or secure setup guides.
+
+## Output quality bar
+
+- Show complete initialization examples.
+- Keep secret handling server-side.
+- When examples include money movement or webhook validation, mention the relevant server-only secrets.

package/ai-skills/rise-auth-and-setup/metadata.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.1.0",
+  "domain": "auth-setup",
+  "package": "riseworks-sdk",
+  "preferredLanguage": "TypeScript",
+  "references": [
+    "../references/TYPES.md",
+    "../references/API_WORKFLOWS.md",
+    "references/SETUP_PATTERNS.md",
+    "https://v2-docs.riseworks.io/"
+  ]
+}

package/ai-skills/rise-auth-and-setup/references/SETUP_PATTERNS.md

@@ -0,0 +1,26 @@
+# Auth and setup patterns
+
+Use this reference when the user needs to initialize `RiseApiClient` correctly.
+
+## Choose the auth mode
+
+- **Use `jwtToken`** when the app already has a valid JWT or only needs read-heavy/manual flows.
+- **Use `riseIdAuth`** when the SDK should manage SIWE/JWT and automatic signing.
+
+## Recommended setup sequence
+
+1. Create typed config with `RiseApiClientOptions`
+2. Initialize `new RiseApiClient(config)`
+3. Verify with `client.me.get()`
+4. Fetch teams or organizations if later steps need nanoids
+
+## Environment defaults
+
+- Ask for `dev`, `stg`, or `prod` when missing.
+- Use `baseUrl` only when the user explicitly needs a custom backend target.
+- Mention `timeout` only when the user is dealing with long-running or unreliable network calls.
+
+## Security defaults
+
+- Keep `privateKey`, `riseIdAuth`, JWTs, and webhook secrets server-side.
+- Recommend secondary wallets for API operations that use signing.

package/ai-skills/rise-debugging-and-errors/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: rise-debugging-and-errors
+description: Troubleshoots Rise SDK integrations, auth issues, webhook validation failures, and payment or withdrawal errors. Use when the user mentions debugging, failed requests, signatures, invalid auth, unexpected responses, or retries.
+compatibility: Any environment. Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise Debugging And Errors
+
+**Note:** Always read the installed `riseworks-sdk` source when implementing—the SDK may have new functions or types not yet reflected in this skill.
+
+## Triage order
+
+1. Confirm environment and auth method.
+2. Confirm the nanoids and request payload shape.
+3. Check whether the request is server-side when secrets or signing are involved.
+4. For webhooks, verify raw body handling and signature validation.
+5. For payments and withdrawals, verify private key availability and approval flow.
+6. Confirm the generated code is using the correct SDK method and exported request/response types.
+
+## Common problem areas
+
+- wrong environment or expired auth
+- missing server-side secret or private key
+- incorrect webhook raw body handling
+- ambiguous payment flow selection
+- missing or invalid nanoids
+- using a write method with JWT auth when the automatic flow requires signing
+- guessing response shapes instead of using SDK types like `{ data, success }`
+- skipping discovery calls (`getTeams()`, `getOrganizations()`) before entity-scoped operations
+
+## API-specific troubleshooting
+
+- **Auth failures**: check `RiseApiClientOptions`, environment, and whether the flow should use `jwtToken` or `riseIdAuth`.
+- **Teams/invites**: verify whether the operation is company-scoped or team-scoped and that the right nanoid type is being used.
+- **Payments/bill pay/withdrawals**: confirm whether the correct automatic or manual typed-data flow was chosen.
+- **Webhooks**: by default, webhook registration is done in the Rise UI; only debug SDK registration code when the user explicitly built programmatic webhook management.
+
+For common SDK method flows, see [references/API_WORKFLOWS.md](../references/API_WORKFLOWS.md).
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Error Handling, Webhooks (Testing & Debugging), API Reference. Suggest when the user needs error formats or deeper troubleshooting guides.
+
+## Output quality bar
+
+- Ask for the failing code path, request type, and error text when missing.
+- Prefer actionable fixes over generic troubleshooting advice.
+- For webhook bugs, include signature and raw-body checks first.

package/ai-skills/rise-payments-workflows/README.md

@@ -0,0 +1,19 @@
+# Rise Payments Workflows Skill
+
+Human-facing notes for the `rise-payments-workflows` skill.
+
+## Purpose
+
+This skill focuses on money-moving and treasury-related SDK flows:
+
+- payment history
+- internal Rise payments
+- external bill pay
+- balance lookup
+- payroll-related payment lookups
+
+## Extra references
+
+- `../references/TYPES.md` — exported payment and bill pay types
+- `../references/API_WORKFLOWS.md` — shared end-to-end SDK flows
+- `references/PAYMENT_PATTERNS.md` — default payment/bill pay patterns

package/ai-skills/rise-payments-workflows/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: rise-payments-workflows
+description: Implements Rise payment, bill pay, and balance workflows with riseworks-sdk. Use when the user mentions payroll, contractor payments, vendor payments, invoices, bill pay, balances, treasury, or withdrawals.
+compatibility: Node.js, TypeScript or JavaScript. Server-side only for signing. Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise Payments Workflows
+
+**Note:** Always read the installed `riseworks-sdk` source when implementing—the SDK may have new functions or types not yet reflected in this skill.
+
+## Classify the request first
+
+- Team payout to existing Rise recipients: use `client.payments.sendPayment()`.
+- External bill pay by email: create the recipient, then send the instant payment.
+- Balance lookup: use `client.entityBalance.get()`.
+- Payroll info: use `client.payroll.getTeamPayroll()`.
+- Payment history or status lookup: use `client.payments.get()`.
+
+## Inputs to collect
+
+- Team, user, or account nanoids (use typed params: `TeamNanoid`, `UserNanoid` when typing)
+- Amount in cents (number for fiat; blockchain amounts may be strings in smallest units)
+- Currency and network when required (`currency_symbol`, `network` e.g. `'arbitrum'`)
+- Recipient email for external bill pay
+- Invoice or service details when present
+
+## Important constraints
+
+- Signed payment flows need a private key on the server or supplied per call.
+- Keep treasury and money-moving code server-side.
+- If the request is ambiguous, ask whether it is an internal Rise payment or external bill pay.
+
+## Preferred SDK surface
+
+### Payments
+- `client.payments.sendPayment({ from, to, pay_now, network })` — automatic; requires `riseIdAuth` or `privateKey`
+- `client.payments.get({ team_nanoid, state, start_date, end_date, query_type })` — list payments
+- Manual flow: `client.payments.getPaymentTypedData(data)` → sign → `client.payments.executePaymentWithSignedData(data)` — the SDK sends a fresh `x-idempotency-key` per call; the execute step takes the payment group id from the signed data, so the two calls must **not** share a key. `sendPayment()` handles this for you.
+
+### Bill pay (external)
+- `client.billPay.createRecipient({ team_nanoid }, data)` — register external recipient by email
+- `client.billPay.sendInstantPayment(data)` — send; requires `riseIdAuth` or `privateKey`
+- Manual flow: `client.billPay.prepareInstantPayment(data)` → sign → `client.billPay.executeInstantPayment(data)`
+
+### Balances
+- `client.entityBalance.get({ nanoid })` — get balance for a team, company, or user entity
+
+### Withdrawals
+- Withdrawals are not available via the SDK: the withdraw endpoints require reCAPTCHA verification headers only a browser session can produce. Point users to the Rise dashboard for withdrawals.
+
+### Payroll
+- `client.payroll.getTeamPayroll({ team_nanoid })` — payroll details for a team
+
+## Common edge cases
+
+- **JWT only**: If the client is created with `jwtToken` and no `riseIdAuth`, automatic `sendPayment` / `sendInstantPayment` will fail; use the manual flow (get typed data, sign elsewhere, execute).
+- **Amounts**: Amounts are in cents; document this in examples. Currency is typically `USD`; network often `arbitrum`.
+- **Dates**: `client.payments.get()` expects `start_date` and `end_date` as `Date` objects (or values the SDK accepts).
+- **Missing team context**: If the user wants payments or bill pay and does not have a `team_nanoid`, call `client.user.getTeams()` first.
+- **Bill pay sequence**: External payments often need two steps: `createRecipient()` first, then `sendInstantPayment()`.
+- **Idempotency**: The batch payment endpoints require an `x-idempotency-key` header. The SDK generates a fresh one per call (POST and PUT use different keys); the server takes the payment group id from the signed data, so the two calls must not share a key. `sendPayment()` handles this automatically.
+- **Safe retries**: Keys are per call — never share one key between the prepare (POST) and the execute (PUT), but DO reuse the same key when retrying the same call. Pass an explicit `idempotencyKey`, keep it for the retry, and wait ~3 seconds between attempts: the server dedups on the key and returns the same transaction, and a 409 "Duplicate request" within the window means the first attempt is still processing. Set `external_id` on each payment — unique per payer team — as the durable idempotency guard.
+
+## When not to use this skill
+
+- User is asking about payments or payroll for a different platform (e.g. Stripe, ADP). Do not assume Rise.
+- User only needs conceptual explanation of "how Rise payments work" with no code. Prefer a short answer unless they ask for implementation.
+
+## Example (team payment)
+
+```ts
+await client.payments.sendPayment({
+  from: teamNanoid,
+  to: [{ to: userNanoid, amount_cents: 10000, currency_symbol: 'USD', invoice_description: 'Contractor pay' }],
+  pay_now: true,
+  network: 'arbitrum',
+})
+```
+
+## Types
+
+- **Queries**: Use `GetPaymentsRequest` and `GetPaymentsResponse` for payment history/status queries.
+- **Payments**: Type payloads with `CreatePaymentsRequest`, `ExecutePaymentsRequest`, `ExecutePaymentsResponse`.
+- **Bill pay**: Type payloads with `CreateExternalRecipientRequest`, `CreateInstantExternalPaymentRequest`, `CreateInstantExternalPaymentResponse`.
+- **Request/response**: Use SDK types for method params and responses where possible. Responses are `{ data, success }`; amounts are typically `amount_cents` (number) or token amounts as strings.
+- **Full type reference**: [references/TYPES.md](../references/TYPES.md) — nanoids, webhook events, API shapes.
+
+## API workflow defaults
+
+- Discover the team first with `client.user.getTeams()` when needed.
+- Use automatic flows when the client has `riseIdAuth`.
+- Use manual typed-data flows when the client only has JWT auth or when the user explicitly wants custom signing.
+
+For full SDK flow patterns, see [references/API_WORKFLOWS.md](../references/API_WORKFLOWS.md).
+For payment-specific generation defaults and sequencing, see [references/PAYMENT_PATTERNS.md](references/PAYMENT_PATTERNS.md).
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Payment Processing, Balance Management, API Reference. Suggest when the user needs currency/network details or full request shapes.
+
+## Output quality bar
+
+- Prefer complete working examples over pseudo-code.
+- Mention approval or review gates for money movement.
+- Reuse the exact SDK method names and argument shapes that exist today.
+- For `billPay`, always pass recipient params as the first argument.

package/ai-skills/rise-payments-workflows/metadata.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.1.0",
+  "domain": "payments",
+  "package": "riseworks-sdk",
+  "preferredLanguage": "TypeScript",
+  "references": [
+    "../references/TYPES.md",
+    "../references/API_WORKFLOWS.md",
+    "references/PAYMENT_PATTERNS.md",
+    "https://v2-docs.riseworks.io/"
+  ]
+}

package/ai-skills/rise-payments-workflows/references/PAYMENT_PATTERNS.md

@@ -0,0 +1,36 @@
+# Payment and bill pay patterns
+
+Use this reference when the user is building payment-related application code.
+
+## Default flow selection
+
+- **Payment history**: `client.payments.get()`
+- **Internal Rise payment**: `client.payments.sendPayment()`
+- **External recipient setup**: `client.billPay.createRecipient({ team_nanoid }, data)`
+- **External instant payment**: `client.billPay.sendInstantPayment()`
+- **Balance lookup**: `client.entityBalance.get({ nanoid })`
+- **Withdrawal**: Withdrawals are not available via the SDK: the withdraw endpoints require reCAPTCHA verification headers only a browser session can produce. Point users to the Rise dashboard for withdrawals.
+
+## Automatic vs manual signing
+
+- Use automatic methods when the client has `riseIdAuth` or an available `privateKey`.
+- Use typed-data flows when the client only has JWT auth or the user explicitly wants custom signing.
+
+## Recommended generation order
+
+1. Discover `team_nanoid` or `account_nanoid` if missing.
+2. Build a typed payload.
+3. Call the SDK method.
+4. Use `response.data`.
+5. Mention approval/review gates for side effects.
+
+## Bill pay specifics
+
+- External recipient registration is often a separate setup step.
+- Do not skip `createRecipient()` when the recipient is not already known to Rise.
+
+## Common values
+
+- `currency_symbol`: usually `'USD'`
+- `network`: often `'arbitrum'`
+- amounts: `amount_cents` for fiat-facing payloads

package/ai-skills/rise-sdk-integration/README.md

@@ -0,0 +1,25 @@
+# Rise SDK Integration Skill
+
+Human-facing notes for the `rise-sdk-integration` skill.
+
+## Purpose
+
+This is the broad "use the SDK correctly" skill. It helps agents choose the
+right `riseworks-sdk` method, discover missing nanoids, and generate typed app
+code instead of pseudo-code.
+
+## When this skill should be used
+
+Use it for general SDK application code involving:
+
+- auth bootstrap
+- team/company discovery
+- payments, bill pay, balances
+- invites and team operations
+- webhook receiver code
+
+## Extra references
+
+- `../references/TYPES.md` — exported request/response and webhook types
+- `../references/API_WORKFLOWS.md` — end-to-end SDK method flows
+- `references/PATTERNS.md` — generation defaults and decision rules for broad SDK tasks