@riseworks/riseworks-sdk 1.0.4

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

@@ -0,0 +1,66 @@
+# V1 migration patterns
+
+Use this reference when the user is actively rewriting legacy Rise V1 code.
+
+## Default recommendation
+
+- Prefer `riseworks-sdk` over raw `/v2/...` HTTP when the project is Node.js,
+  TypeScript, or JavaScript.
+- Preserve existing behavior first.
+- Only introduce new B2B-only capabilities after parity is reached.
+
+## Recommended migration order
+
+1. Inventory the V1 endpoints and wrappers still in use.
+2. Rebuild authentication and client initialization.
+3. Replace numeric IDs with nanoids and add discovery calls.
+4. Swap endpoint logic for SDK methods.
+5. Update response/error handling.
+6. Re-test side-effectful flows and signing paths.
+
+## ID migration defaults
+
+- `teamId` -> `team_nanoid`
+- `talentId` -> `user_nanoid`
+- company-scoped operations often need `company_nanoid`
+- do not invent numeric-to-nanoid conversion rules; fetch or provide the real
+  nanoids
+
+## Auth migration defaults
+
+- If the new code can keep a private key server-side, prefer
+  `new RiseApiClient({ riseIdAuth: { riseId, privateKey } })`.
+- If the application already issues valid JWTs, use
+  `new RiseApiClient({ jwtToken })`.
+- If JWT is available but automatic signing is not, use typed-data methods and
+  execute with a signature.
+
+## Flow selection rules
+
+### Read-heavy migrations
+
+- `client.me.get()`
+- `client.user.getTeams()`
+- `client.user.getOrganizations()`
+- `client.teams.getUsers()`
+- `client.entityBalance.get()`
+- `client.payments.get()`
+
+### Side-effectful migrations
+
+- payments -> `sendPayment()` or typed-data flow
+- manager invites -> `sendManagerInvite()` or typed-data flow
+- 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.
+
+### Webhook migrations
+
+- split webhook migration into:
+  - event payload and event-name migration
+  - signature verification migration
+  - endpoint rollout / cutover strategy
+
+## Output bar
+
+- Show the old V1 surface and the new B2B surface.
+- Mention missing inputs such as nanoids or auth material.
+- Prefer complete migration-ready examples over abstract summaries.

package/ai-skills/rise-webhooks/README.md

@@ -0,0 +1,41 @@
+# Rise Webhooks Skill
+
+Human-facing notes for the `rise-webhooks` skill.
+
+## Purpose
+
+This skill helps agents implement two related webhook surfaces:
+
+- **registration/management** of webhook endpoints using `riseworks-sdk`
+- **receiving/validation** of incoming webhook events using `WebhookValidator`
+
+## Why this skill has extra files
+
+`SKILL.md` is the concise agent-facing document.
+
+The files in `references/` provide deeper, task-specific guidance so agents can
+load extra detail only when needed:
+
+- `references/REGISTRATION.md` — admin/settings UI and server-side registration
+- `references/HANDLER.md` — receiving endpoint, validation, idempotent handling
+
+## Scope
+
+Use this skill when users ask for:
+
+- webhook setup
+- webhook registration UI
+- webhook endpoint management
+- signature validation
+- delivery history
+- typed webhook event handlers
+
+## Main SDK surfaces
+
+- `client.webhooks.list()`
+- `client.webhooks.register()`
+- `client.webhooks.update()`
+- `client.webhooks.delete()`
+- `client.webhooks.test()`
+- `client.webhooks.getDeliveryHistory()`
+- `WebhookValidator`

package/ai-skills/rise-webhooks/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: rise-webhooks
+description: Implements Rise webhook registration, validation, and event handlers. Use when the user mentions webhooks, event delivery, webhook secrets, webhook signatures, delivery history, or validating Rise events.
+compatibility: Server-side (Node.js, etc.). Works with Claude Code, Cursor, Windsurf, Codex.
+metadata:
+  author: Rise Works
+  version: "1.0"
+---
+
+# Rise Webhooks
+
+**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 approach
+
+- Use `WebhookValidator` from `riseworks-sdk` for signature validation.
+- Keep the webhook secret server-side.
+- Preserve the raw request body when validating signatures.
+- Return a `2xx` quickly, then hand off heavier processing asynchronously when possible.
+
+## Think in two surfaces
+
+- **Registration and management**: Default to the Rise UI / dashboard for webhook creation and event selection. Use SDK registration only when the user explicitly wants programmatic admin automation. If SDK registration is used, the actual call must stay server-side because it includes the secret.
+- **Receiving and processing**: The webhook endpoint that validates signatures and handles `RiseWebhookEvent` payloads.
+- If the user asks to "set up webhooks", ask whether they need:
+  - guidance for registering the webhook in the Rise UI,
+  - a settings/admin flow to programmatically create and manage webhook endpoints,
+  - a receiving endpoint to validate and process events,
+  - or both.
+
+## TypeScript types
+
+Import event and management types from the SDK so handlers and API calls are correctly typed:
+
+- **Validated event**: `validator.validateEvent()` / `validateEventSafe().event` returns `RiseWebhookEvent`. Narrow by `event.event_type` to get typed payloads (e.g. `PaymentSentV2`, `DepositReceivedV2`).
+- **Register/list/update**: Use `RegisterWebhookRequest`, `ListWebhooksResponse`, `WebhookListItem`, `DeliveryHistoryItem`, `WebhookEndpointNanoid` for params and responses.
+- **Event type strings**: Use literal strings for `events` when registering (e.g. `'payment.sent'`, `'deposit.received'`). Same values appear as `event.event_type` on payloads.
+
+For the full type list and imports, see [references/TYPES.md](../references/TYPES.md).
+
+## Management surface
+
+- List webhooks with `client.webhooks.list()`.
+- Register endpoints with `client.webhooks.register()` — payload shape: `RegisterWebhookRequest` (company_nanoid, url, events, secret, optional team_nanoid, name, description).
+- Delete or inspect delivery history with the extended webhook helpers when needed.
+- For most apps, prefer guiding the user to:
+  - create the webhook in the Rise UI,
+  - select only the events they need,
+  - store the secret server-side,
+  - then implement the receiver endpoint in code.
+- Only when the user explicitly wants programmatic webhook management, prefer generating:
+  - a UI form or settings screen for webhook configuration,
+  - a server action / backend route that builds `RegisterWebhookRequest`,
+  - and a secure server-side call to `client.webhooks.register()`.
+
+## Handler expectations
+
+- Validate the incoming signature before trusting payload contents.
+- Log the event type and relevant identifiers for support and debugging.
+- Fail closed on signature errors.
+
+## Common edge cases
+
+- **Raw body**: Signature validation requires the exact raw request body. If the framework parses JSON automatically, the agent must use the raw body (e.g. `req.rawBody` or read the stream before parsing).
+- **Secret**: The webhook secret must match the one used when registering the endpoint; keep it server-side and never log it.
+- **Idempotency**: Handlers may receive the same event more than once; design for idempotency where possible.
+- **UI vs browser**: `RegisterWebhookRequest` often comes from UI form state, but the browser should not call `client.webhooks.register()` with the secret directly. Put the SDK call in a server action, route handler, or backend service.
+- **Event selection**: Start with a minimal set of events (`payment.sent`, `payment.group.created`, `deposit.received`) instead of subscribing to everything by default.
+- **Default registration path**: Unless the user explicitly asks for admin automation, assume webhook creation happens in the Rise UI rather than through the SDK.
+
+## When not to use this skill
+
+- User is asking about outbound HTTP calls from their app (e.g. calling Rise API), not receiving webhooks. Use rise-sdk-integration for API usage.
+- User mentions webhooks for a different product (e.g. Stripe). Do not assume Rise.
+
+## Example (validation and typed handler)
+
+```ts
+import { WebhookValidator } from 'riseworks-sdk'
+import type { RiseWebhookEvent, PaymentSentV2, DepositReceivedV2 } from 'riseworks-sdk'
+
+const validator = new WebhookValidator(process.env.WEBHOOK_SECRET!)
+const rawBody = getRawBodyFromRequest(req) // framework-specific: use raw body
+const signature = req.headers['x-rise-signature'] ?? req.headers['x-signature']
+
+const event = validator.validateEvent(rawBody, signature) as RiseWebhookEvent
+// Narrow by event_type for typed payload access
+if (event.event_type === 'payment.sent') {
+  const ev = event as PaymentSentV2
+  console.log(ev.payment.nanoid, ev.payment.amount_cents)
+}
+if (event.event_type === 'deposit.received') {
+  const ev = event as DepositReceivedV2
+  console.log(ev.deposit.nanoid, ev.deposit.entity_nanoid)
+}
+```
+
+For a non-throwing check, use `validator.validateEventSafe(rawBody, signature)` and read `result.isValid` (and `result.code` for the failure reason). `validateEvent` throws `WebhookValidationError` on failure.
+
+## Example (register with types)
+
+```ts
+import { RiseApiClient } from 'riseworks-sdk'
+import type { RegisterWebhookRequest } from 'riseworks-sdk'
+
+const client = new RiseApiClient({ environment: 'stg', jwtToken })
+const body: RegisterWebhookRequest = {
+  company_nanoid: 'co-xxx',
+  url: 'https://api.example.com/webhooks/rise',
+  events: ['payment.sent', 'deposit.received'],
+  secret: process.env.WEBHOOK_SECRET!,
+}
+const { data } = await client.webhooks.register(body)
+// data.webhook_nanoid is WebhookEndpointNanoid
+```
+
+## Preferred implementation shape
+
+- If the user wants webhook setup generally, prefer:
+  - Rise UI for webhook registration,
+  - then code for the receiver endpoint.
+- If the user names a UI framework and explicitly wants programmatic webhook management, prefer:
+  - typed form state in the UI,
+  - validation on submit,
+  - a server action or backend handler that maps form values to `RegisterWebhookRequest`,
+  - and then `client.webhooks.register(body)` on the server.
+- For non-UI backend tasks, generate a plain typed function that receives validated inputs and registers the webhook.
+
+## Additional references
+
+- **Registration flow**: [references/REGISTRATION.md](references/REGISTRATION.md) — admin/settings UI flow, server-action pattern, `RegisterWebhookRequest`, list/test/update patterns.
+- **Receiver flow**: [references/HANDLER.md](references/HANDLER.md) — signature validation, typed handlers, idempotency.
+
+## Documentation
+
+- **Rise B2B API**: [https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/) — Webhook Overview, Quick Setup, Security & Validation, Event Types, Management, Testing & Debugging. Suggest when the user needs event schemas or delivery details.
+- **SDK types**: [references/TYPES.md](../references/TYPES.md) — Webhook event types, request/response types, nanoids.
+
+## Output quality bar
+
+- Show framework-specific code only when the user names the framework.
+- Prefer concrete server examples over browser examples.
+- When troubleshooting, suggest delivery history inspection and signature verification first.

package/ai-skills/rise-webhooks/metadata.json

@@ -0,0 +1,13 @@
+{
+  "version": "1.1.0",
+  "domain": "webhooks",
+  "package": "riseworks-sdk",
+  "primarySurfaces": ["registration-management", "receiver-validation"],
+  "preferredLanguage": "TypeScript",
+  "references": [
+    "../references/TYPES.md",
+    "references/REGISTRATION.md",
+    "references/HANDLER.md",
+    "https://v2-docs.riseworks.io/"
+  ]
+}

package/ai-skills/rise-webhooks/references/HANDLER.md

@@ -0,0 +1,60 @@
+# Webhook receiver and handler implementation
+
+Use this reference when the user needs the **incoming webhook endpoint**.
+
+## Default server shape
+
+1. Read the **raw request body**
+2. Read `X-Rise-Signature`
+3. Validate with `WebhookValidator`
+4. Return `2xx` quickly
+5. Process the event asynchronously or idempotently
+
+## Types to use
+
+```ts
+import { WebhookValidator } from 'riseworks-sdk'
+import type {
+  RiseWebhookEvent,
+  PaymentSentV2,
+  PaymentGroupCreatedV2,
+  DepositReceivedV2,
+  InviteAcceptedV2,
+  WithdrawAccountDuplicatedDetectedV2,
+} from 'riseworks-sdk'
+```
+
+## Example
+
+```ts
+const validator = new WebhookValidator(process.env.WEBHOOK_SECRET!)
+
+const event = validator.validateEvent(rawBody, signature)
+
+switch (event.event_type) {
+  case 'payment.sent': {
+    const e = event as PaymentSentV2
+    console.log(e.payment.nanoid)
+    break
+  }
+  case 'deposit.received': {
+    const e = event as DepositReceivedV2
+    console.log(e.deposit.nanoid)
+    break
+  }
+}
+```
+
+## Important constraints
+
+- Signature verification requires the **exact raw body**
+- The secret used here must match the secret used during registration
+- Do not block the HTTP response on slow downstream work
+- Handle duplicate deliveries with idempotency checks when side effects exist
+
+## Good default behaviors
+
+- Log `event_type`, `event_version`, and `idempotency_key`
+- Reject invalid signatures with `400` or `401`
+- Treat unknown event types as non-fatal and log them
+- Keep framework-specific code minimal unless the user asked for a framework

package/ai-skills/rise-webhooks/references/REGISTRATION.md

@@ -0,0 +1,113 @@
+# Webhook registration and management
+
+Use this reference when the user needs to **create, edit, test, or list** Rise
+webhook endpoints programmatically.
+
+## Default recommendation
+
+For most customers, webhook registration should be done in the **Rise UI**:
+
+1. Create the endpoint in the Rise app/dashboard
+2. Select the event types there
+3. Store the secret server-side
+4. Implement the receiving endpoint in code
+
+Only use the SDK registration flow when the user explicitly wants:
+
+- backend-managed webhook provisioning
+- an admin/settings UI inside their own app
+- automated setup across environments or tenants
+
+## Default architecture
+
+Programmatic registration is usually part of an **admin UI**, **settings page**, or
+**internal platform flow**:
+
+1. The UI collects the endpoint URL, selected events, optional team/company
+scope, description, and activation state.
+2. A server action, route handler, or backend service validates those values.
+3. The server builds a `RegisterWebhookRequest` (or `UpdateWebhookRequest`) and
+calls `client.webhooks.register()` / `client.webhooks.update()`.
+
+Do **not** put the webhook secret directly in browser-only code.
+
+## Types to use
+
+```ts
+import { RiseApiClient } from 'riseworks-sdk'
+import type {
+  RegisterWebhookRequest,
+  UpdateWebhookRequest,
+  ListWebhooksRequest,
+  ListWebhooksResponse,
+  TestWebhookRequest,
+  TestWebhookResponse,
+  WebhookListItem,
+  WebhookEndpointNanoid,
+} from 'riseworks-sdk'
+```
+
+## Methods to prefer
+
+- `client.webhooks.list(params)` — list existing webhook endpoints
+- `client.webhooks.register(body)` — create a new endpoint
+- `client.webhooks.update(webhookNanoid, body)` — update an endpoint
+- `client.webhooks.delete(webhookNanoid)` — delete an endpoint
+- `client.webhooks.test(webhookNanoid, body)` — send a test delivery
+- `client.webhooks.getDeliveryHistory(webhookNanoid, params)` — inspect results
+
+## Registration example
+
+```ts
+import { RiseApiClient } from 'riseworks-sdk'
+import type { RegisterWebhookRequest } from 'riseworks-sdk'
+
+export async function registerRiseWebhook(input: RegisterWebhookRequest) {
+  const client = new RiseApiClient({
+    environment: 'stg',
+    jwtToken: process.env.RISE_JWT!,
+  })
+
+  const { data } = await client.webhooks.register(input)
+  return data
+}
+```
+
+## UI-oriented pattern
+
+If the user is building a UI, prefer code shaped like this:
+
+- **client/UI**: typed form values
+- **server action / route handler**: validation + `RegisterWebhookRequest`
+- **SDK call**: `client.webhooks.register(body)`
+
+Example fields to expose in the UI:
+
+- `url`
+- `events`
+- `company_nanoid`
+- `team_nanoid` (optional)
+- `name`
+- `description`
+- `is_active`
+
+Only collect `secret` in a server-safe flow. If the UI must accept the secret,
+submit it to a server action immediately and do not reuse it in browser logic.
+
+## Event selection guidance
+
+Recommend starting with a small event set:
+
+- `payment.sent`
+- `payment.group.created`
+- `deposit.received`
+- `invite.accepted`
+
+Avoid subscribing to every event unless the user explicitly needs that breadth.
+
+## Output quality bar
+
+- If the user mentions a UI, generate both the form model and the server-side
+registration path.
+- Use real exported SDK types instead of anonymous object shapes.
+- Mention role/permission expectations for admin settings screens.