@riseworks/riseworks-sdk 1.0.4

package/README.md

@@ -0,0 +1,240 @@
+# Rise SDK
+
+Official TypeScript/JavaScript SDK for Rise B2B integrations.
+
+It includes:
+- A typed API client for B2B and `v2` endpoints
+- Claude-style AI coding skills you can copy into `.claude/skills/`
+- Built-in webhook validation
+
+## Installation
+
+```bash
+npm install riseworks-sdk
+```
+
+## Quick Start
+
+```ts
+import { RiseApiClient } from 'riseworks-sdk'
+
+const client = new RiseApiClient({
+  environment: 'stg',
+  jwtToken: process.env.RISE_JWT_TOKEN!,
+})
+
+const me = await client.me.get()
+const organizations = await client.user.getOrganizations()
+```
+
+## AI Coding Skills
+
+The npm package ships reusable Claude-style `SKILL.md` files for coding assistants.
+
+**Add skills from the CLI (no copy-paste):**
+
+```bash
+# Add all skills to all supported agents (default)
+npx riseworks-sdk add-skills
+
+# Add to one agent only
+npx riseworks-sdk add-skills --agent cursor rise-sdk-integration rise-webhooks
+
+# List available skills and supported agents
+npx riseworks-sdk add-skills --list
+```
+
+Or copy manually from `node_modules/riseworks-sdk/ai-skills/` into `.claude/skills/`, `.cursor/skills/`, etc.
+
+Available skills:
+
+- `rise-sdk-integration`
+- `rise-v1-migration`
+- `rise-payments-workflows`
+- `rise-webhooks`
+- `rise-teams-and-invites`
+- `rise-auth-and-setup`
+- `rise-security-and-approvals`
+- `rise-debugging-and-errors`
+
+Use these when you want Claude Code or a similar coding assistant to write better Rise integration code.
+
+## Low-Level API Groups
+
+The lower-level client remains available for direct endpoint access.
+
+- `client.auth`
+- `client.webhooks`
+- `client.company`
+- `client.organizations`
+- `client.entityBalance`
+- `client.invites`
+- `client.me`
+- `client.payments`
+- `client.billPay`
+- `client.payroll`
+- `client.team`
+- `client.teams`
+- `client.user`
+
+Withdrawals are not part of the SDK, and `client.company` / `client.organizations` are read-only: those endpoints require reCAPTCHA verification headers that only a browser session can produce, so they cannot be called server-to-server. Use the Rise dashboard for withdrawals and company profile changes.
+
+Every `POST`/`PUT` request automatically carries a fresh `x-idempotency-key` header. Pass your own key to `payments.prepare/create/execute`, `getPaymentTypedData`, `executePaymentWithSignedData`, or `sendPayment` (as `idempotencyKey`) when you want retries of the same logical operation deduplicated on your key instead.
+
+## Branded ID types
+
+The SDK exports branded nanoid types for API params and responses. Use them when you have a plain `string` from a response and need to pass it to another method:
+
+| Type | Use case |
+|------|----------|
+| `TeamNanoid` | `payments.get()`, `teams.get()`, `teams.getUsers()`, `billPay.*`, payroll, invites |
+| `UserNanoid` | `teams.getMemberSettings()`, company members |
+| `CompanyNanoid` | `teams.create()`, company APIs, webhooks |
+| `WithdrawAccountNanoid` | Typing withdraw-account ids in webhook event payloads |
+| `WebhookEndpointNanoid` | `webhooks.get()`, `webhooks.update()`, `webhooks.test()` |
+| `WebhookDeliveryNanoid` | `webhooks.retryDelivery()`, delivery history |
+| `InviteNanoid` | Invite execute/list flows |
+| `TransactionNanoid` | Typing payment response `transaction` fields |
+
+```ts
+import {
+  RiseApiClient,
+  type TeamNanoid,
+  type UserNanoid,
+  type CompanyNanoid,
+  type WithdrawAccountNanoid,
+  type WebhookEndpointNanoid,
+  type WebhookDeliveryNanoid,
+  type InviteNanoid,
+  type TransactionNanoid,
+} from 'riseworks-sdk'
+
+const client = new RiseApiClient({ environment: 'stg', jwtToken: '…' })
+const { data } = await client.user.getTeams()
+const teamNanoid = data?.teams?.[0]?.nanoid  // string
+
+await client.payments.get({
+  team_nanoid: teamNanoid as TeamNanoid,
+  state: 'all',
+  query_type: 'payable',
+  start_date: new Date(),
+  end_date: new Date(),
+})
+```
+
+## Examples
+
+### Teams
+
+```ts
+const team = await client.teams.get({ team_nanoid: 'te_123' })
+
+await client.teams.update(
+  { team_nanoid: 'te_123' },
+  { name: 'Finance Ops' },
+)
+const members = await client.teams.getUsers({ team_nanoid: 'te_123' })
+```
+
+### Bill Pay
+
+```ts
+await client.billPay.createRecipient(
+  { team_nanoid: 'te_123' },
+  { email: 'vendor@example.com' },
+)
+
+const payment = await client.billPay.sendInstantPayment({
+  from: 'te_123',
+  amount_cents: 125000,
+  currency_symbol: 'USD',
+  external_recipient_email: 'vendor@example.com',
+  payment_data: {
+    role_description: 'Design work',
+    invoice_description: 'Invoice INV-2026-001',
+    services_description: 'Landing page design',
+    payment_details: 'Net 15',
+    rise_sow: false,
+  },
+})
+```
+
+### Treasury
+
+```ts
+const balance = await client.entityBalance.get({
+  nanoid: 'te_123',
+})
+```
+
+### Batch payments
+
+```ts
+const result = await client.payments.sendPayment({
+  from: 'te_123' as TeamNanoid,
+  to: [{ to: 'us_123' as UserNanoid, amount_cents: 50000, currency_symbol: 'USD' }],
+  pay_now: true,
+})
+
+console.log(result.data.transaction)
+// Recipients the server skipped or flagged as recently paid are surfaced —
+// check them instead of assuming every recipient in `to` was paid.
+console.log(result.failed_payments)
+console.log(result.duplicates)
+```
+
+Before signing, `sendPayment` verifies the server-provided typed data against your request (expected chain id for the environment, payment count, max per-payment amount) and throws instead of signing anything broader than what you asked for.
+
+### Webhooks
+
+```ts
+import express from 'express'
+import { WebhookValidator } from 'riseworks-sdk'
+
+const app = express()
+const validator = new WebhookValidator(process.env.RISE_WEBHOOK_SECRET!)
+
+app.post('/rise-webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const event = validator.validateEvent(
+      req.body,
+      req.headers['x-rise-signature'] as string,
+    )
+
+    console.log(event.event_type)
+    res.status(200).json({ received: true })
+  } catch (error) {
+    res.status(400).json({
+      error: error instanceof Error ? error.message : 'Webhook validation failed',
+    })
+  }
+})
+```
+
+## Exports
+
+The package exports:
+- `RiseApiClient`
+- `WebhookValidator`
+- Webhook event types
+- Generated API request/response types
+
+## Authentication
+
+You can authenticate with either:
+- `jwtToken`
+- `riseIdAuth` for automatic SIWE-based JWT generation and refresh
+
+```ts
+const client = new RiseApiClient({
+  environment: 'prod',
+  riseIdAuth: {
+    riseId: process.env.RISE_ID!,
+    privateKey: process.env.RISE_PRIVATE_KEY!,
+  },
+})
+```
+
+## License
+
+MIT

package/ai-skills/README.md

@@ -0,0 +1,28 @@
+# Rise AI Coding Skills
+
+This package ships reusable `SKILL.md` files (Agent Skills format) for AI-assisted Rise SDK integrations. The same skills work across **Claude Code, Cursor, Windsurf, and Codex**. Skills describe the SDK at a point in time; the **installed SDK source is the source of truth** for current methods, types, and behavior—agents are instructed to read the SDK code when implementing.
+
+Skills live directly under `ai-skills/` (e.g. `ai-skills/rise-sdk-integration/SKILL.md`). The format is agent-agnostic, so the CLI copies that content into each agent’s folder (`.claude/skills`, `.cursor/skills`, etc.).
+
+**Add skills via CLI:**
+
+```bash
+npx riseworks-sdk add-skills                     # add all skills to all agents (default)
+npx riseworks-sdk add-skills --agent cursor rise-sdk-integration rise-webhooks
+npx riseworks-sdk add-skills --list              # list skills and supported agents
+```
+
+Or copy from `node_modules/riseworks-sdk/ai-skills/` into your project's agent skills directory (e.g. `.claude/skills/`, `.cursor/skills/`).
+
+**Reference:** `ai-skills/references/TYPES.md` — TypeScript types (webhook events, request/response shapes, nanoids). Copied with skills when using the CLI so skills can link to `../references/TYPES.md`.
+
+Available skills:
+
+- `rise-sdk-integration`
+- `rise-v1-migration`
+- `rise-payments-workflows`
+- `rise-webhooks`
+- `rise-teams-and-invites`
+- `rise-auth-and-setup`
+- `rise-security-and-approvals`
+- `rise-debugging-and-errors`

package/ai-skills/STANDARDS.md

@@ -0,0 +1,66 @@
+# Skill authoring standards (reference)
+
+This package follows the [Agent Skills](https://agentskills.io/specification) format and best practices so skills trigger reliably and produce good output.
+
+## Frontmatter (required)
+
+- **name**: Max 64 chars, lowercase letters, numbers, hyphens only. Must match the skill directory name.
+- **description**: Max 1024 chars. Primary trigger for agents—include **what** the skill does and **when** to use it. Use third person or imperative (“Use this skill when…”). Add keywords users might say (e.g. “payments”, “migration”, “webhooks”).
+
+Optional fields we can use:
+
+- **compatibility**: Short note on environment (e.g. “Node.js, TypeScript” or “Claude Code, Cursor, Windsurf, Codex”).
+- **metadata**: e.g. `author`, `version` for traceability.
+
+## Body structure (recommended by spec)
+
+- **Step-by-step instructions** where the task has a clear sequence.
+- **Common edge cases** (what can go wrong, what to validate).
+- **Examples** of inputs and outputs (or minimal code snippets) so the agent can mirror real usage.
+- **When not to use** (boundaries) so the skill does not trigger on unrelated tasks.
+
+## Conciseness (Claude best practices)
+
+- Only include what the agent does not already know. Omit generic explanations.
+- Keep the main `SKILL.md` under ~500 lines. Move long reference material to `references/` and link from the body.
+- Prefer one level of reference (e.g. `references/REFERENCE.md`) rather than deep chains.
+
+## Progressive disclosure
+
+- Agents load only **name** and **description** at discovery (~100 tokens).
+- When the task matches, they load the full **SKILL.md** (aim for <5000 tokens).
+- Put extra docs in `references/` or `scripts/` and reference them so they are loaded only when needed.
+
+## Optional authoring files
+
+We can also keep extra authoring and human-facing files in each skill directory when they add value:
+
+- **`README.md`**: short human summary of the skill, its scope, and file layout.
+- **`metadata.json`**: version, domain, references, and authoring metadata for tooling and maintainers.
+- **`references/*.md`**: detailed implementation guidance for agents to load on demand.
+
+Important:
+
+- `SKILL.md` remains the **agent-facing compiled document** and should stay concise.
+- `README.md` and `metadata.json` help maintainers and future tooling, but should not replace `SKILL.md`.
+- Prefer adding support files only where they improve output quality materially; avoid adding boilerplate to every skill directory without a clear use.
+
+## Triggering (optimizing descriptions)
+
+- Describe **user intent** and **context**, not internal implementation.
+- Include both explicit triggers (“when the user says X”) and implicit ones (“even if they don’t say ‘Rise SDK’”).
+- Test with ~20 eval queries (10 should-trigger, 10 should-not-trigger) and refine the description so it does not over- or under-trigger.
+
+## SDK as source of truth
+
+- Skills document the SDK at a point in time and may not reflect the latest API. **Include a note in SDK-related skills** that agents should always read the installed SDK code (e.g. `node_modules/riseworks-sdk`) for current methods, types, and behavior—the SDK may have new functions or types that are not yet described in the skills.
+
+## Documentation
+
+- Point to the official **Rise B2B API docs** ([https://v2-docs.riseworks.io/](https://v2-docs.riseworks.io/)) in a "Documentation" section when it helps: Quickstart, Authentication, SDK, Webhooks, API Reference. That way the agent can suggest the right guide or reference instead of duplicating content in the skill.
+
+## Validation
+
+- Ensure `name` matches the directory and fits the spec (length, characters).
+- Keep `description` under 1024 characters.
+- You can validate with: `skills-ref validate ./skill-name` (from [agentskills/agentskills](https://github.com/agentskills/agentskills)).

package/ai-skills/references/API_WORKFLOWS.md

@@ -0,0 +1,200 @@
+# Rise SDK API workflows
+
+Use this reference when the user is building application code with
+`riseworks-sdk` and needs the actual SDK method flow, not just type names.
+
+## Default approach
+
+- Start by identifying the entity the user already has: company, team, user, or
+  withdraw account.
+- If they do not have the required nanoid yet, generate discovery calls first.
+- Prefer the SDK method that directly matches the requested workflow.
+- Use exported request/response types instead of anonymous object shapes.
+
+## Common discovery flows
+
+### Auth bootstrap
+
+```ts
+const client = new RiseApiClient({
+  environment: 'stg',
+  jwtToken,
+})
+
+const me = await client.me.get()
+const teams = await client.user.getTeams()
+const orgs = await client.user.getOrganizations()
+```
+
+Use this when the user needs current-user, company, or initial team/company
+context.
+
+### Team and company discovery
+
+- `client.user.getTeams()` — first stop when a payment or member operation needs
+  a `team_nanoid`
+- `client.user.getOrganizations()` — first stop when company-scoped operations
+  need a `company_nanoid`
+- `client.company.getUsers({ nanoid })` — get company users once company context
+  is known
+- `client.teams.getUsers({ team_nanoid })` — get payees or members for a team
+
+## Teams workflows
+
+### Team CRUD
+
+```ts
+const created = await client.teams.create(body)
+const team = await client.teams.get({ team_nanoid })
+await client.teams.update({ team_nanoid }, body)
+await client.teams.delete({ team_nanoid })
+```
+
+### Team settings and members
+
+```ts
+const settings = await client.teams.getSettings({ team_nanoid })
+await client.teams.updateSettings({ team_nanoid }, body)
+
+const users = await client.teams.getUsers({ team_nanoid })
+const member = await client.teams.getMemberSummary({ team_nanoid, user_nanoid })
+await client.teams.removeMember({ team_nanoid, user_nanoid })
+```
+
+## Invite workflows
+
+### Regular employee/contractor invites
+
+No signing required:
+
+```ts
+await client.invites.send({
+  nanoid: companyOrTeamNanoid,
+  invites: [{ email, role }],
+})
+```
+
+### Manager invites
+
+Automatic signing requires `riseIdAuth` or `privateKey`:
+
+```ts
+await client.invites.sendManagerInvite({
+  nanoid,
+  emails,
+  role,
+})
+```
+
+Manual flow:
+
+```ts
+const typed = await client.invites.getManagerInviteTypedData(data)
+// sign typed.data.typed_data
+await client.invites.executeManagerInviteWithSignedData(dataWithSignature)
+```
+
+## Payment workflows
+
+### Query payments
+
+```ts
+const payments = await client.payments.get({
+  team_nanoid,
+  state: 'all',
+  query_type: 'payable',
+  start_date: new Date(start),
+  end_date: new Date(end),
+})
+```
+
+Use `team_nanoid` from `client.user.getTeams()` when the user does not already
+have one.
+
+### Internal Rise payments
+
+Automatic flow:
+
+```ts
+await client.payments.sendPayment({
+  from: teamNanoid,
+  to: [{ to: userNanoid, amount_cents: 10000, currency_symbol: 'USD' }],
+  pay_now: true,
+  network: 'arbitrum',
+})
+```
+
+Manual flow — the execute step takes the payment group id from the signed data,
+so the two calls must use **different** idempotency keys (a shared key collides
+with the 3s request-dedup window). Omitting the key lets each call generate its
+own:
+
+```ts
+const typed = await client.payments.getPaymentTypedData(body)
+// sign typed.data.typed_data
+await client.payments.executePaymentWithSignedData(bodyWithSignature)
+```
+
+`sendPayment()` does the same end to end.
+
+Safe retries: keys are per call — never share one key between the prepare
+(POST) and the execute (PUT). When retrying the *same* call, do the opposite:
+pass an explicit `idempotencyKey`, reuse that exact key on the retry, and wait
+about 3 seconds between attempts. The server dedups on the key and returns the
+same transaction; a 409 "Duplicate request" within the window means the first
+attempt is still processing. This applies to prepare and execute alike. Set
+`external_id` on each payment as the durable guard — it is unique per payer
+team, so a duplicate submission is rejected rather than paid twice.
+
+## Bill pay workflows
+
+### External recipients
+
+```ts
+await client.billPay.createRecipient(
+  { team_nanoid },
+  { email: 'vendor@example.com' },
+)
+```
+
+### Instant external payment
+
+```ts
+await client.billPay.sendInstantPayment({
+  from: teamNanoid,
+  amount_cents: 10000,
+  currency_symbol: 'USD',
+  network: 'arbitrum',
+  external_recipient_email: 'vendor@example.com',
+  payment_data: {
+    role_description: 'Vendor',
+    invoice_description: 'March invoice',
+    rise_sow: false,
+  },
+})
+```
+
+## Balance and withdrawal workflows
+
+### Balance lookup
+
+```ts
+const balance = await 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.
+
+## Webhooks
+
+- **Default registration path**: the Rise UI / dashboard.
+- **Programmatic management**: only use SDK webhook registration when the user
+  explicitly wants admin automation or backend-managed webhook configuration.
+- **Receiving webhooks**: use `WebhookValidator` and `RiseWebhookEvent`.
+
+## Output quality bar
+
+- Generate the discovery call when the required nanoid is missing.
+- Use the exact SDK method names that exist in `riseworks-sdk`.
+- Prefer complete SDK flows over pseudo-code.