@riseworks/riseworks-sdk 1.0.4

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

@@ -0,0 +1,130 @@
+---
+name: rise-sdk-integration
+description: Writes and reviews TypeScript or JavaScript integrations with riseworks-sdk. Use when the user mentions Rise SDK, RiseApiClient, riseworks-sdk, integrating Rise into an app, or asks for teams, invites, payments, bill pay, balances, webhooks, payroll, or company management code.
+compatibility: Node.js, TypeScript or JavaScript. Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise SDK Integration
+
+## Important: verify against the SDK source
+
+**Always read the SDK code** when implementing or reviewing integrations. The SDK package may be updated with new functions, types, and method signatures; the skills and references in this repo can lag behind. Treat the installed `riseworks-sdk` source (e.g. `node_modules/riseworks-sdk` or the package’s TypeScript/API surface) as the source of truth for available methods, request/response types, and behavior.
+
+## Decide the mode first
+
+- If the user is building application code, use `RiseApiClient` directly.
+- Do not invent or reference a `client.skills.*` layer. That helper layer was removed.
+
+## Defaults
+
+- Import from `riseworks-sdk`.
+- Prefer TypeScript unless the user asks for another language.
+- Keep `privateKey`, `riseIdAuth`, JWTs, and webhook secrets server-side.
+- Ask for the missing environment, auth method, and relevant nanoids when the task depends on them.
+- If the user is missing a `team_nanoid` or `company_nanoid`, generate the discovery call first (`client.user.getTeams()` or `client.user.getOrganizations()`).
+
+## Use the current SDK surface
+
+### Auth and identity
+- Setup: `new RiseApiClient({ environment, jwtToken })` or `new RiseApiClient({ environment, riseIdAuth: { riseId, privateKey } })`
+- Current user: `client.me.get()`
+- Manual SIWE: `client.auth.getSiwe({ wallet, riseid })`, `client.auth.verifySiwe({ message, sig, nonce })`
+
+### Organizations and teams
+- `client.user.getOrganizations()` — list organizations for the current user
+- `client.user.getTeams()` — list teams for the current user
+- `client.teams.create(data)` — create a team
+- `client.teams.get({ team_nanoid })` — get team details
+- `client.teams.update({ team_nanoid }, data)` — update team info
+- `client.teams.delete({ team_nanoid })` — delete a team
+- `client.teams.getUsers({ team_nanoid })` — list team members
+- `client.teams.removeMember({ team_nanoid, user_nanoid })` — remove a member
+- `client.teams.getMemberSummary({ team_nanoid, user_nanoid })` — member details
+- `client.teams.getSettings({ team_nanoid })` / `client.teams.updateSettings({ team_nanoid }, data)` — team settings
+- `client.teams.getMemberSettings({ team_nanoid, user_nanoid })` / `client.teams.updateMemberSettings({ team_nanoid, user_nanoid }, data)` — member settings
+- `client.company.getUsers({ nanoid })` — list company users
+
+### Invites
+- `client.invites.get({ company_nanoid })` — list invites
+- `client.invites.send({ nanoid, invites })` — invite employees/contractors
+- `client.invites.sendManagerInvite({ nanoid, emails, role })` — invite managers (requires `riseIdAuth` or `privateKey`)
+- Manual: `client.invites.getManagerInviteTypedData()` + sign + `client.invites.executeManagerInviteWithSignedData()`
+
+### Payments
+- `client.payments.sendPayment({ from, to, pay_now, network })` — automatic (requires `riseIdAuth`)
+- `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)`
+
+### Bill pay (external recipients)
+- `client.billPay.createRecipient(data)` — register an external recipient
+- `client.billPay.sendInstantPayment(data)` — send instant payment to external recipient (requires `riseIdAuth`)
+- Manual: `client.billPay.prepareInstantPayment(data)` + sign + `client.billPay.executeInstantPayment(data)`
+
+### Balances
+- `client.entityBalance.get({ nanoid })` — get entity balance
+- 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 })` — get payroll details for a team
+
+### Webhooks
+- `client.webhooks.list(params)` — list webhook endpoints
+- `client.webhooks.register(data)` — register a new endpoint
+- `client.webhooks.update(webhookNanoid, data)` — update an endpoint
+- `client.webhooks.delete(webhookNanoid)` — delete an endpoint
+- `client.webhooks.test(webhookNanoid, data)` — send a test event
+- `client.webhooks.getDeliveryHistory(webhookNanoid, params)` — delivery history
+- `WebhookValidator` — validate incoming webhook signatures
+
+## Types
+
+- **API call types**: Prefer exported request/response types for SDK methods instead of hand-written object shapes. Common examples: `RiseApiClientOptions`, `TeamParams`, `CreateTeamRequest`, `GetBalanceRequest`, `GetBalanceResponse`, `CreatePaymentsRequest`, `CreateInstantExternalPaymentRequest`, `PostManagerInvitesRequest`.
+- **Nanoids**: Use branded types for params and responses — `TeamNanoid`, `CompanyNanoid`, `UserNanoid`, `WebhookEndpointNanoid`, `WithdrawAccountNanoid`, etc. — all exported from the SDK.
+- **Responses**: All client methods return `{ data, success }`; use `response.data` for the payload. Type `data` from the method’s return type when using TypeScript.
+- **Webhooks**: Use `RiseWebhookEvent` and event-specific types (`PaymentSentV2`, `DepositReceivedV2`, etc.); narrow by `event.event_type`. For full type list and request/response shapes, see [references/TYPES.md](../references/TYPES.md).
+
+## Typed examples
+
+- `const config: RiseApiClientOptions = { environment: 'stg', jwtToken }`
+- `const params: TeamParams = { team_nanoid }`
+- `const body: CreateTeamRequest = { ... }`
+- `const payment: CreatePaymentsRequest = { from, to, pay_now: true, network: 'arbitrum' }`
+- `const response: GetBalanceResponse = await client.entityBalance.get({ nanoid })`
+
+## API workflow defaults
+
+- **Auth/bootstrap**: `client.me.get()` to confirm auth; `client.user.getTeams()` / `client.user.getOrganizations()` to fetch entity context.
+- **Team/member operations**: discover the team first, then use `client.teams.*` or `client.company.getUsers()`.
+- **Payments/bill pay**: choose between automatic flow (`riseIdAuth` or `privateKey`) and manual typed-data flow (`get*TypedData()` -> sign -> `execute*WithSignedData()`).
+- **Webhooks**: receiving endpoints belong in `rise-webhooks`; webhook registration should default to the Rise UI unless the user explicitly wants backend-admin automation.
+
+For fuller method-to-type mapping and common SDK flows, see [references/API_WORKFLOWS.md](../references/API_WORKFLOWS.md).
+For broad generation defaults across mixed SDK tasks, see [references/PATTERNS.md](references/PATTERNS.md).
+
+## When not to use this skill
+
+- User is asking about a different SDK or API (e.g. Stripe, generic REST). Do not trigger for non-Rise integrations.
+- User only needs conceptual explanation of “what is Rise” with no code. Prefer a short answer unless they ask for integration steps.
+
+## Example (minimal)
+
+```ts
+import { RiseApiClient } from 'riseworks-sdk'
+const client = new RiseApiClient({ environment: 'stg', jwtToken: process.env.RISE_JWT })
+const { data } = await client.user.getTeams()
+const teamNanoid = data?.teams?.[0]?.nanoid
+// use teamNanoid with client.payments.get(), client.teams.getUsers(), etc.
+```
+
+## Documentation
+
+- **Rise B2B API docs**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Quickstart, Authentication, SDK Installation/Configuration, API Reference, Webhooks. Suggest this when the user needs full reference or step-by-step guides.
+
+## Output quality bar
+
+- Prefer real SDK code over pseudo-code.
+- Use exported names that exist today in `riseworks-sdk`.
+- For side-effectful flows, call out approval and audit requirements.

package/ai-skills/rise-sdk-integration/metadata.json

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

package/ai-skills/rise-sdk-integration/references/PATTERNS.md

@@ -0,0 +1,28 @@
+# Broad SDK integration patterns
+
+Use this reference when the request spans multiple Rise domains or when it is
+not obvious which SDK method to start with.
+
+## Generation defaults
+
+- Generate `RiseApiClient` setup first when auth is missing.
+- Generate discovery calls first when a `team_nanoid` or `company_nanoid` is missing.
+- Prefer exported request/response types from `riseworks-sdk`.
+- Prefer SDK method calls over raw HTTP.
+- For write flows, mention whether automatic signing (`riseIdAuth`) or manual typed-data signing is required.
+
+## Decision rules
+
+- **Need current-user or bootstrap context**: use `client.me.get()`.
+- **Need teams**: use `client.user.getTeams()`.
+- **Need organizations/companies**: use `client.user.getOrganizations()`.
+- **Need company users**: use `client.company.getUsers({ nanoid })`.
+- **Need team users**: use `client.teams.getUsers({ team_nanoid })`.
+- **Need payments**: go to the payments methods, and fetch a team first if needed.
+- **Need webhooks**: registration defaults to Rise UI; receiver code uses `WebhookValidator`.
+
+## Output quality bar
+
+- Generate real SDK code with imports from `riseworks-sdk`.
+- Do not invent helper layers.
+- If the request spans many surfaces, structure the answer in the same order the app would execute the flow.

package/ai-skills/rise-security-and-approvals/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: rise-security-and-approvals
+description: Applies security and approval guidance for Rise SDK integrations. Use when the user is building payment, webhook, or agent workflows and needs safe server-side patterns, approvals, or audit controls.
+compatibility: Any environment. Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise Security And Approvals
+
+## Apply these guardrails
+
+- Keep `privateKey`, `riseIdAuth`, JWTs, and webhook secrets on the server.
+- Never place signing or secret material in browser code.
+- Add approvals or confirmation gates before payments, bill pay, and webhook mutations.
+- Prefer auditable service boundaries for money-moving actions.
+
+## Review checklist
+
+- Is the code server-side?
+- Are secrets loaded from environment variables or secure storage?
+- Is there an approval step before side effects?
+- Is there enough logging or audit metadata for support and finance review?
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Authentication, Understanding Private Keys, Secondary Wallets, Webhook Security. Suggest when the user asks about key handling or validation.
+
+## Output quality bar
+
+- When generating code, default to safe server patterns.
+- If the user asks for a browser example involving secrets or signing, warn and redirect to a server implementation.

package/ai-skills/rise-teams-and-invites/README.md

@@ -0,0 +1,13 @@
+# Rise Teams And Invites Skill
+
+Human-facing notes for the `rise-teams-and-invites` skill.
+
+## Purpose
+
+This skill covers team, organization, member, and invite flows in `riseworks-sdk`.
+
+## Extra references
+
+- `../references/TYPES.md` — exported team and invite request/response types
+- `../references/API_WORKFLOWS.md` — shared SDK discovery and workflow patterns
+- `references/TEAM_PATTERNS.md` — practical defaults for discovery, CRUD, and invites

package/ai-skills/rise-teams-and-invites/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: rise-teams-and-invites
+description: Implements organization, team, member, and invite flows with riseworks-sdk. Use when the user mentions organizations, teams, members, invites, contractors, employees, admins, or manager invites in Rise.
+compatibility: Node.js, TypeScript or JavaScript. Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise Teams And Invites
+
+**Note:** Always read the installed `riseworks-sdk` source when implementing—the SDK may have new functions or types not yet reflected in this skill.
+
+## Pick the right scope
+
+- Organization discovery: `client.user.getOrganizations()`.
+- Team discovery: `client.user.getTeams()`.
+- Team CRUD: `client.teams.create(data)`, `client.teams.get({ team_nanoid })`, `client.teams.update({ team_nanoid }, data)`, `client.teams.delete({ team_nanoid })`.
+- Team settings: `client.teams.getSettings({ team_nanoid })`, `client.teams.updateSettings({ team_nanoid }, data)`.
+- Team members: `client.teams.getUsers({ team_nanoid })`, `client.teams.getMemberSummary({ team_nanoid, user_nanoid })`, `client.teams.removeMember({ team_nanoid, user_nanoid })`.
+- Member settings: `client.teams.getMemberSettings({ team_nanoid, user_nanoid })`, `client.teams.updateMemberSettings({ team_nanoid, user_nanoid }, data)`.
+- Company users: `client.company.getUsers({ nanoid })`.
+- List invites: `client.invites.get({ company_nanoid })`.
+- Member invites: `client.invites.send({ nanoid, invites })`.
+- Manager invites: `client.invites.sendManagerInvite({ nanoid, emails, role })` (requires `riseIdAuth` or `privateKey`).
+- Manual manager invite: `client.invites.getManagerInviteTypedData(data)` + sign + `client.invites.executeManagerInviteWithSignedData(data)`.
+
+## Inputs to confirm
+
+- Whether the action is organization-scoped or team-scoped
+- The target nanoid (team nanoid or company nanoid)
+- The invite role
+- The invitee emails and any known prefill data
+- Whether the user wants discovery/listing, team CRUD, member management, or invites
+
+## Notes on signing
+
+- `sendManagerInvite()` uses EIP-712 signing internally; the client must be initialized with `riseIdAuth` or the caller must supply `privateKey`.
+- Regular `invites.send()` for employees and contractors does not require signing.
+
+## Types
+
+- Use `TeamParams` and `TeamUserParams` for route params.
+- Use `CreateTeamRequest`, `UpdateTeamRequest`, `GetTeamResponse`, `GetTeamUsersResponse`, `GetTeamSettingsResponse`, `UpdateTeamSettingsRequest` for typed team flows.
+- Use `GetInvitesRequest`, `GetInvitesResponse`, `PostInvitesRequest`, `PostInvitesResponse`, `PostManagerInvitesRequest`, and `PostManagerInvitesResponse` for invite flows.
+- Use branded nanoid types (`TeamNanoid`, `CompanyNanoid`, `UserNanoid`, `InviteNanoid`) for params and stored identifiers.
+
+## API workflow defaults
+
+- If the user needs a `team_nanoid`, start with `client.user.getTeams()`.
+- If the user needs a `company_nanoid`, start with `client.user.getOrganizations()`.
+- For regular member invites, prefer `client.invites.send()` first.
+- Only use manager invite signing flows when the requested role actually requires it.
+
+For fuller SDK workflow guidance, see [references/API_WORKFLOWS.md](../references/API_WORKFLOWS.md).
+For team and invite decision rules, see [references/TEAM_PATTERNS.md](references/TEAM_PATTERNS.md).
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Team Management, Core Concepts (roles, RBAC), API Reference. Suggest when the user needs role definitions or org/team structure details.
+
+## Output quality bar
+
+- Use the exact Rise role values required by the SDK.
+- Prefer direct SDK calls over pseudo-helper abstractions.
+- If a workflow changes permissions or membership, mention review and audit expectations.

package/ai-skills/rise-teams-and-invites/metadata.json

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

package/ai-skills/rise-teams-and-invites/references/TEAM_PATTERNS.md

@@ -0,0 +1,25 @@
+# Team and invite patterns
+
+Use this reference when the user needs discovery, CRUD, membership, or invite logic.
+
+## Default flow selection
+
+- **Need team context**: `client.user.getTeams()`
+- **Need organization/company context**: `client.user.getOrganizations()`
+- **Need company users**: `client.company.getUsers({ nanoid })`
+- **Need team members**: `client.teams.getUsers({ team_nanoid })`
+- **Need team CRUD**: `client.teams.create/get/update/delete`
+- **Need regular invites**: `client.invites.send()`
+- **Need manager/admin invites**: `client.invites.sendManagerInvite()` or manual typed-data flow
+
+## Invite rules
+
+- Default to regular invites when the role does not require signing.
+- Use manager invite flows only for roles that need EIP-712 signing.
+- Mention whether the operation is team-scoped or company-scoped.
+
+## Output quality bar
+
+- Generate discovery calls when the user does not already have the required nanoid.
+- Use branded nanoid types where possible.
+- Call out permission and review implications when membership or admin roles change.

package/ai-skills/rise-v1-migration/README.md

@@ -0,0 +1,22 @@
+# Rise V1 Migration Skill
+
+Human-facing notes for the `rise-v1-migration` skill.
+
+## Purpose
+
+This skill helps migrate legacy Rise V1 integrations to the B2B API and
+`riseworks-sdk`.
+
+It is meant for cases where the existing code still uses:
+
+- direct `/v1/...` HTTP calls
+- numeric IDs like `teamId` and `talentId`
+- old SIWE/auth wrappers
+- legacy payment, invite, balance, or webhook logic
+
+## Extra references
+
+- `../references/TYPES.md` — exported SDK types used in migrated code
+- `../references/API_WORKFLOWS.md` — shared end-to-end SDK workflows
+- `references/MIGRATION_PATTERNS.md` — migration rollout order and decision rules
+- `references/ENDPOINT_MAPPINGS.md` — concrete V1 to B2B mappings

package/ai-skills/rise-v1-migration/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: rise-v1-migration
+description: Migrates legacy Rise V1 API code to the B2B v2 API. V1 had no SDK—only direct HTTP to /v1/ endpoints. Use when the user mentions migration, legacy Rise code, /v1 endpoints, numeric IDs, or moving to B2B.
+compatibility: Node.js, TypeScript or JavaScript. Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise V1 Migration
+
+**Note:** Always read the installed `riseworks-sdk` source when implementing—the SDK may have new functions or types not yet reflected in this skill.
+
+## Migration mindset
+
+- Treat this as **V1 HTTP -> B2B SDK or `/v2` HTTP**, not "old SDK -> new SDK". V1 had no SDK.
+- Preserve behavior first, then improve ergonomics with B2B-only features.
+- Prefer `RiseApiClient` unless the user explicitly wants raw HTTP examples.
+- When the user only shows old endpoints, infer the closest B2B workflow and state any assumptions.
+
+## Classify the migration first
+
+- **Auth bootstrap**: old SIWE endpoints or custom auth wrapper.
+- **Teams and members**: old `teamId` / `talentId` paths.
+- **Payments**: old pay or batch-pay endpoints.
+- **Balances**: old riseId-based balance lookup.
+- **Invites**: employee/contractor or manager invite flows.
+- **Webhooks**: old webhook payload format, verification, or event names.
+- **Mixed legacy service**: a wrapper class touching several V1 areas.
+
+## Default migration rules
+
+- Replace numeric IDs and `teamId` / `talentId` terminology with nanoids.
+- Update auth to `jwtToken` or `riseIdAuth`.
+- Replace V1 response handling with B2B `{ success, data }`.
+- For signing flows, prefer automatic SDK methods when `riseIdAuth` or `privateKey` is available.
+- If only JWT is available, switch to typed-data flow (`get*TypedData()` -> sign -> `execute*WithSignedData()`).
+- If the required `team_nanoid`, `company_nanoid`, or `user_nanoid` is missing, generate discovery calls first.
+
+## Types
+
+- Prefer exported request/response types from `riseworks-sdk` instead of anonymous objects.
+- Use branded nanoid types (`TeamNanoid`, `CompanyNanoid`, `UserNanoid`) where possible.
+- Type client setup with `RiseApiClientOptions`.
+- For migration output that includes payments, invites, or balances, use the matching request/response types from [references/TYPES.md](../references/TYPES.md).
+
+## Migration phases
+
+### 1. Inventory the V1 surface
+
+- Identify every `/v1/...` path still in use.
+- Identify whether the old code is read-only, side-effectful, or signing-related.
+- Record what identifiers the old code currently has: numeric IDs, `rise_id`, wallet address, JWT, etc.
+
+### 2. Rebuild auth first
+
+- V1 auth code using `GET /v1/api/siwe` + `POST /v1/api/siwe` should become:
+  - `new RiseApiClient({ environment, riseIdAuth: { riseId, privateKey } })` for SDK-managed auth, or
+  - `client.auth.getSiwe({ wallet, riseid })` + `client.auth.verifySiwe({ message, sig, nonce })` for manual SIWE.
+- If the application already has a valid JWT, initialize with `new RiseApiClient({ environment, jwtToken })`.
+
+### 3. Replace identifiers
+
+- `teamId` -> `team_nanoid`
+- `talentId` / legacy user references -> `user_nanoid`
+- riseId-based entity lookup often becomes a B2B discovery step followed by a nanoid-based SDK call
+
+### 4. Swap endpoint logic for SDK flows
+
+### Teams and members
+
+- `GET /v1/teams` -> `client.user.getTeams()`
+- `GET /v1/teams/{teamId}/talent` -> `client.teams.getUsers({ team_nanoid })`
+- `GET /v1/teams/{teamId}/talent/{talentId}` -> `client.teams.getMemberSummary({ team_nanoid, user_nanoid })`
+- `DELETE /v1/teams/{teamId}/talent/{talentId}` -> `client.teams.removeMember({ team_nanoid, user_nanoid })`
+
+### Payments
+
+- `POST /v1/payments/pay`
+- `POST /v1/payments/batch-pay`
+- `PUT /v1/payments/pay`
+- `PUT /v1/payments/batch-pay`
+  -> automatic: `client.payments.sendPayment({ from, to, pay_now, network })`
+  -> manual: `client.payments.getPaymentTypedData()` + sign + `client.payments.executePaymentWithSignedData()`
+
+- `GET /v1/payments/` -> `client.payments.get({ team_nanoid, state, start_date, end_date, query_type })`
+
+### Balances
+
+- `GET /v1/riseid/{rise_id}/balance` -> `client.entityBalance.get({ nanoid })`
+
+### Invites
+
+- `GET /v1/invites/` -> `client.invites.get({ company_nanoid })`
+- `POST /v1/invites/` for employees/contractors -> `client.invites.send({ nanoid, invites })`
+- `POST /v1/invites/` for managers -> automatic: `client.invites.sendManagerInvite({ nanoid, emails, role })`
+- Manager invite manual flow -> `client.invites.getManagerInviteTypedData()` + sign + `client.invites.executeManagerInviteWithSignedData()`
+
+### Webhooks
+
+- Old webhook migrations belong partly here and partly in `rise-webhooks`.
+- For receiver code, use `WebhookValidator` and `RiseWebhookEvent`.
+- For payload/event-name changes, see `references/ENDPOINT_MAPPINGS.md` and the webhook migration docs.
+
+### 5. Update response and error handling
+
+- V1 code may have consumed raw arrays or endpoint-specific JSON.
+- B2B SDK calls return `{ success, data }`; use `response.data`.
+- When rewriting raw HTTP to raw `/v2` HTTP, preserve the B2B response envelope in the examples.
+
+## New B2B-only features
+
+- Team CRUD: `client.teams.create()`, `client.teams.update()`, `client.teams.delete()`
+- Team and member settings
+- Organizations via `client.user.getOrganizations()`
+- Bill pay, payroll, webhooks, and richer typed flows
+
+## API workflow defaults
+
+- **Bootstrap**: `client.me.get()` then `client.user.getTeams()` / `client.user.getOrganizations()` when the migrated code needs entity context.
+- **Teams**: discover the team first, then move to `client.teams.*`.
+- **Payments/invites**: choose automatic methods when signing material exists, otherwise use typed-data flows.
+- **Webhooks**: migrate event handling and validation separately from webhook registration.
+
+For general SDK call sequences, see [references/API_WORKFLOWS.md](../references/API_WORKFLOWS.md).
+For migration decision rules and rollout order, see [references/MIGRATION_PATTERNS.md](references/MIGRATION_PATTERNS.md).
+For concrete V1 -> B2B mappings, see [references/ENDPOINT_MAPPINGS.md](references/ENDPOINT_MAPPINGS.md).
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Quickstart, Core Concepts, Authentication, SDK, API Reference.
+- **Migration guide**: `/guides/migrating-from-v1` in the docs.
+- **Webhook migration guide**: `/webhooks/reference/migration` when the legacy integration includes webhooks.
+
+## Migration checklist
+
+1. Inventory every `/v1/...` path and any numeric IDs still flowing through the code.
+2. Rebuild auth with `jwtToken` or `riseIdAuth`.
+3. Replace numeric IDs with nanoids and add discovery calls where needed.
+4. Replace V1 endpoint logic with `RiseApiClient` methods or `/v2/...` HTTP.
+5. Update response handling to `{ success, data }`.
+6. Revisit signing flows for payments, manager invites, and other typed-data operations.
+7. If webhooks are involved, migrate payload handling and signature verification separately.
+8. Only after parity is achieved, adopt B2B-only features.
+
+## Common edge cases
+
+- **No nanoids yet**: do not fake a conversion from numeric IDs; generate discovery calls or ask how the app will map old IDs to B2B entities.
+- **JWT-only environment**: use manual typed-data flows for operations that cannot use automatic signing.
+- **Behavioral drift risk**: preserve the original business behavior before adopting new B2B-only features or cleaner abstractions.
+- **Response shape mismatch**: update reads from raw arrays or direct fields to `response.data`.
+- **Webhook confusion**: migrating webhook receivers is not the same as programmatic webhook registration.
+- **Mixed legacy wrapper**: if one service touches teams, invites, and payments, split the migration by domain and keep shared auth/bootstrap code separate.
+
+## When not to use this skill
+
+- User is not migrating from Rise V1 (e.g. first-time integration or migrating from another provider). Use rise-sdk-integration instead.
+- User only asks what B2B is with no migration intent.
+
+## Example migration pattern
+
+**V1 (no SDK):** `fetch(baseUrl + '/v1/teams/' + teamId + '/talent', { headers: { Authorization: 'Bearer ' + jwt } })`
+
+**B2B (SDK):**
+
+```ts
+const client = new RiseApiClient({ environment: 'stg', jwtToken })
+const teams = await client.user.getTeams()
+const teamNanoid = teams.data?.teams?.[0]?.nanoid
+
+if (!teamNanoid) {
+  throw new Error('No team_nanoid found for migrated member lookup')
+}
+
+const members = await client.teams.getUsers({ team_nanoid: teamNanoid })
+```
+
+## Output quality bar
+
+- Prefer B2B SDK code over raw fetch when the user is on Node/TS.
+- Show the migration in terms of old behavior -> new SDK flow.
+- Use real SDK methods and exported types that exist today in `riseworks-sdk`.
+- When the old code is ambiguous, preserve behavior first and call out assumptions.
+- Do not imply V1 had an SDK; frame migration as “V1 HTTP → B2B (SDK or v2 HTTP)”.

package/ai-skills/rise-v1-migration/metadata.json

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

package/ai-skills/rise-v1-migration/references/ENDPOINT_MAPPINGS.md

@@ -0,0 +1,72 @@
+# V1 to B2B endpoint mappings
+
+Use this reference when the user shows legacy endpoint names or old wrapper
+methods and needs the closest B2B replacement.
+
+## Authentication
+
+- `GET /v1/api/siwe` -> `client.auth.getSiwe({ wallet, riseid })` or
+  `GET /v2/auth/siwe`
+- `POST /v1/api/siwe` -> `client.auth.verifySiwe({ message, sig, nonce })` or
+  `POST /v2/auth/verify`
+- SDK-managed auth -> `new RiseApiClient({ environment, riseIdAuth })`
+
+## Teams and members
+
+- `GET /v1/teams` -> `client.user.getTeams()` or `GET /v2/user/teams`
+- `GET /v1/teams/{teamId}/talent` -> `client.teams.getUsers({ team_nanoid })`
+  or `GET /v2/teams/{team_nanoid}/users`
+- `GET /v1/teams/{teamId}/talent/{talentId}` ->
+  `client.teams.getMemberSummary({ team_nanoid, user_nanoid })` or
+  `GET /v2/teams/{team_nanoid}/member/{user_nanoid}/summary`
+- `DELETE /v1/teams/{teamId}/talent/{talentId}` ->
+  `client.teams.removeMember({ team_nanoid, user_nanoid })` or
+  `DELETE /v2/teams/{team_nanoid}/member/{user_nanoid}`
+
+## Payments
+
+- `POST /v1/payments/pay` -> `client.payments.sendPayment()` or
+  `POST /v2/payments` + `PUT /v2/payments`
+- `PUT /v1/payments/pay` -> `client.payments.sendPayment()` or
+  `POST /v2/payments` + `PUT /v2/payments`
+- `POST /v1/payments/batch-pay` -> `client.payments.sendPayment()` or
+  `POST /v2/payments` + `PUT /v2/payments`
+- `PUT /v1/payments/batch-pay` -> `client.payments.sendPayment()` or
+  `POST /v2/payments` + `PUT /v2/payments`
+- `POST /v1/payments/batch-pay/intents` ->
+  `client.payments.getPaymentTypedData()` + sign +
+  `client.payments.executePaymentWithSignedData()`
+- `GET /v1/payments/` -> `client.payments.get()` or `GET /v2/payments`
+
+## Balances
+
+- `GET /v1/riseid/{rise_id}/balance` -> `client.entityBalance.get({ nanoid })`
+  or `GET /v2/balance?nanoid={nanoid}`
+
+## Invites
+
+- `GET /v1/invites/` -> `client.invites.get({ company_nanoid })` or
+  `GET /v2/invites`
+- `POST /v1/invites/` for employee/contractor invites ->
+  `client.invites.send({ nanoid, invites })` or `POST /v2/invites`
+- `POST /v1/invites/` for manager invites ->
+  `client.invites.sendManagerInvite({ nanoid, emails, role })` or
+  `POST /v2/invites/manager` + `PUT /v2/invites/manager`
+
+## Webhooks
+
+- v1 event envelope -> v2 `RiseWebhookEvent` envelope
+- v1 public-key verification -> v2 HMAC validation via `WebhookValidator`
+- v1 event types:
+  - `deposit.deposit_received` -> `deposit.received`
+  - `payment.payment_sent` -> `payment.sent`
+  - `pay_schedules.pay_schedule_created` -> `payment.group.created`
+  - `invites.invite_accepted` -> `invite.accepted`
+  - `account_duplicated.detected` -> `withdraw_account.duplicated_detected`
+
+## Notes
+
+- Prefer SDK methods in migration output when the user is already in a JS/TS
+  codebase.
+- When the user explicitly wants HTTP mappings, keep the `/v2/...` equivalents
+  beside the SDK methods.