Cursor Skill

integrate-unprice-sdk

Integrate and troubleshoot the @unprice/api TypeScript SDK in server-side Node.js, Next.js, Hono, or edge applications. Use when onboarding Unprice customers, checking access, enforcing or recording usage, reserving budgets for multi-step workloads, handling Unprice API results,

LLM Mart · 0 points · 15 views 90 listing impressions 0 install-command copies
Download jhonsfran-unprice-skills_integrate-unprice-sdk-36a9d90.zip · 16 KB

Install

skills CLI npx skills add https://github.com/jhonsfran/unprice/tree/main/skills/integrate-unprice-sdk
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jhonsfran-unprice@llmmart
Git git clone https://github.com/jhonsfran/unprice.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole jhonsfran/unprice collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Integrate the Unprice SDK

Build the smallest correct Unprice integration at the boundary that owns the paid action. Preserve the host project's architecture and use the installed SDK types as the exact contract.

Route the request first. Defining or changing the project's plans, prices, features, or limits is configuration: read configuration-workflow.md and stop at reviewUrl. Checking access, enforcing, or recording usage at runtime: read operation-selection.md and follow the workflow below.

Workflow

  1. Inspect the project before editing.

    • Identify the package manager, framework, server boundary, environment validation, customer identity model, logging style, and test conventions.
    • Search for existing @unprice/api, Unprice, UNPRICE_TOKEN, customer ID mappings, feature slugs, event slugs, and idempotency helpers.
    • Reuse an existing Unprice client or integration owner instead of creating a parallel path.
  2. Identify the commercial decision.

    • Read operation-selection.md.
    • Choose one primary runtime path before writing code.
    • Do not infer product configuration from UI labels or plan names.
    • Keep stable capability and event identifiers in the host. Unprice owns plan configuration: names, membership, prices, limits, the default signup plan, and feature-to-plan rules. Hosts that own plan selection may pass an explicit, published, policy-approved planSlug or planVersionId at signup without copying that configuration.
    • For included metered usage plus overage, or a customer-specific spend cap, read configuration-workflow.md.
  3. Confirm prerequisites.

    • Require a published plan version and the actual plan, feature, event, and meter property slugs.
    • Determine whether the application already stores an Unprice customerId.
    • Use customers.signUp when Unprice must provision or map the customer money path.
    • Ask for missing business identifiers instead of inventing them.
  4. Install or reuse the SDK.

    • Use the project's existing package manager.
    • Add @unprice/api only when it is absent.
    • Create one server-only Unprice client using the project's environment conventions.
  5. Implement the integration.

    • Read integration-patterns.md for the selected path.
    • Keep the API token out of browser bundles, client components, public environment variables, logs, fixtures, and committed files.
    • Handle SDK/API errors separately from valid commercial denials.
    • Preserve one stable idempotency key for the same logical mutation across retries.
    • Make fail-open versus fail-closed behavior an explicit host-application policy.
  6. Verify before finishing.

    • Read verification.md.
    • Add focused tests for success, API error, commercial denial, and retry behavior.
    • Run the smallest relevant formatter, typecheck, and test commands from the host project.
    • Do not make a live Unprice call unless the user requests it and provides an appropriate non-production environment.

Non-negotiable rules

  • Keep Unprice API keys server-side.
  • Check stable feature slugs; never branch product behavior on plan display names.
  • Use access.entitlements.current for a customer-wide capability or billing UI snapshot. Use access.check when one paid action needs one current decision.
  • Treat access.check as a read-only decision.
  • Never use usage.record as a spend gate.
  • Do not begin paid work after a denied usage.consume or rejected run reservation.
  • A run reservation authorizes a finite currency envelope; it does not constrain a downstream provider by itself. Before starting variable-cost work, derive a conservative worst-case cost for the request, reserve that amount, and pass the matching cap to the provider (for example, maxTokens). If the known input plus the minimum useful output cannot fit, deny before the provider call. Never use post-response runs.consume as the only spend gate.
  • A nonzero runs.start reserves wallet funds. An active subscription alone is insufficient: provision a wallet grant, credit line, or top-up large enough for the expected simultaneous reservations.
  • Close short-lived runs in finally. For a deliberately long-lived conversation, set expiresAt, reuse its stable idempotency key throughout that window, and explicitly close it on cancellation or failure.
  • End a run as failed after exceptions or rejected consumption; do not report it as completed.
  • Reuse the same idempotency key when retrying the same logical mutation.
  • Do not replace a repository's existing billing or authorization owner with route-level orchestration when a service or use-case layer owns that behavior.
  • Do not guess exact request or response fields. Inspect the installed @unprice/api types or the official OpenAPI contract.

Contract precedence

When sources disagree, use this order:

  1. Installed @unprice/api TypeScript types.
  2. Current official OpenAPI document at https://docs.unprice.dev/openapi.json.
  3. Bundled references in this skill for stable behavioral guidance.
  4. Individual documentation examples.

If a bundled example no longer typechecks, adapt it to the installed contract and report the drift instead of weakening type safety.

Files (unprice)
  • agents
    • openai.yaml 227 B
      Loading…
  • references
    • configuration-workflow.md 9.1 KB
      Loading…
    • integration-patterns.md 11.4 KB
      Loading…
    • operation-selection.md 7.6 KB
      Loading…
    • verification.md 4.5 KB
      Loading…
  • SKILL.md 5.9 KB
    ---
    name: integrate-unprice-sdk
    description: Integrate and troubleshoot the @unprice/api TypeScript SDK in server-side Node.js, Next.js, Hono, or edge applications. Use when onboarding Unprice customers, checking access, enforcing or recording usage, reserving budgets for multi-step workloads, handling Unprice API results, reviewing an existing Unprice integration, adding customer-spend authorization before paid work runs, or writing a project's plan, feature, price, and limit configuration into Unprice.
    license: MIT
    ---
    
    # Integrate the Unprice SDK
    
    Build the smallest correct Unprice integration at the boundary that owns the paid action. Preserve
    the host project's architecture and use the installed SDK types as the exact contract.
    
    Route the request first. Defining or changing the project's plans, prices, features, or limits is
    configuration: read [configuration-workflow.md](references/configuration-workflow.md) and stop at
    `reviewUrl`. Checking access, enforcing, or recording usage at runtime: read
    [operation-selection.md](references/operation-selection.md) and follow the workflow below.
    
    ## Workflow
    
    1. Inspect the project before editing.
       - Identify the package manager, framework, server boundary, environment validation, customer
         identity model, logging style, and test conventions.
       - Search for existing `@unprice/api`, `Unprice`, `UNPRICE_TOKEN`, customer ID mappings, feature
         slugs, event slugs, and idempotency helpers.
       - Reuse an existing Unprice client or integration owner instead of creating a parallel path.
    
    2. Identify the commercial decision.
       - Read [operation-selection.md](references/operation-selection.md).
       - Choose one primary runtime path before writing code.
       - Do not infer product configuration from UI labels or plan names.
       - Keep stable capability and event identifiers in the host. Unprice owns plan configuration:
         names, membership, prices, limits, the default signup plan, and feature-to-plan rules.
         Hosts that own plan selection may pass an explicit, published, policy-approved `planSlug`
         or `planVersionId` at signup without copying that configuration.
       - For included metered usage plus overage, or a customer-specific spend cap,
         read [configuration-workflow.md](references/configuration-workflow.md).
    
    3. Confirm prerequisites.
       - Require a published plan version and the actual plan, feature, event, and meter property slugs.
       - Determine whether the application already stores an Unprice `customerId`.
       - Use `customers.signUp` when Unprice must provision or map the customer money path.
       - Ask for missing business identifiers instead of inventing them.
    
    4. Install or reuse the SDK.
       - Use the project's existing package manager.
       - Add `@unprice/api` only when it is absent.
       - Create one server-only `Unprice` client using the project's environment conventions.
    
    5. Implement the integration.
       - Read [integration-patterns.md](references/integration-patterns.md) for the selected path.
       - Keep the API token out of browser bundles, client components, public environment variables,
         logs, fixtures, and committed files.
       - Handle SDK/API errors separately from valid commercial denials.
       - Preserve one stable idempotency key for the same logical mutation across retries.
       - Make fail-open versus fail-closed behavior an explicit host-application policy.
    
    6. Verify before finishing.
       - Read [verification.md](references/verification.md).
       - Add focused tests for success, API error, commercial denial, and retry behavior.
       - Run the smallest relevant formatter, typecheck, and test commands from the host project.
       - Do not make a live Unprice call unless the user requests it and provides an appropriate
         non-production environment.
    
    ## Non-negotiable rules
    
    - Keep Unprice API keys server-side.
    - Check stable feature slugs; never branch product behavior on plan display names.
    - Use `access.entitlements.current` for a customer-wide capability or billing UI snapshot. Use
      `access.check` when one paid action needs one current decision.
    - Treat `access.check` as a read-only decision.
    - Never use `usage.record` as a spend gate.
    - Do not begin paid work after a denied `usage.consume` or rejected run reservation.
    - A run reservation authorizes a finite currency envelope; it does not constrain a downstream
      provider by itself. Before starting variable-cost work, derive a conservative worst-case cost
      for the request, reserve that amount, and pass the matching cap to the provider (for example,
      `maxTokens`). If the known input plus the minimum useful output cannot fit, deny before the
      provider call. Never use post-response `runs.consume` as the only spend gate.
    - A nonzero `runs.start` reserves wallet funds. An active subscription alone is
      insufficient: provision a wallet grant, credit line, or top-up large enough
      for the expected simultaneous reservations.
    - Close short-lived runs in `finally`. For a deliberately long-lived conversation,
      set `expiresAt`, reuse its stable idempotency key throughout that window, and
      explicitly close it on cancellation or failure.
    - End a run as `failed` after exceptions or rejected consumption; do not report it as `completed`.
    - Reuse the same idempotency key when retrying the same logical mutation.
    - Do not replace a repository's existing billing or authorization owner with route-level
      orchestration when a service or use-case layer owns that behavior.
    - Do not guess exact request or response fields. Inspect the installed `@unprice/api` types or the
      official OpenAPI contract.
    
    ## Contract precedence
    
    When sources disagree, use this order:
    
    1. Installed `@unprice/api` TypeScript types.
    2. Current official OpenAPI document at `https://docs.unprice.dev/openapi.json`.
    3. Bundled references in this skill for stable behavioral guidance.
    4. Individual documentation examples.
    
    If a bundled example no longer typechecks, adapt it to the installed contract and report the drift
    instead of weakening type safety.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.