@ambushsoftworks/nestjs-subscriptions

A NestJS module for apps where paying unlocks features, built on RevenueCat: store and web purchases, access checks, grants, and subscription events.

Not released. The package is being built against the plan in docs/planning/, which records every decision and why it was taken. Start at docs/planning/README.md.

What it does

• Receives RevenueCat webhooks — verified, deduplicated, and used as a trigger to fetch the customer from RevenueCat rather than trusted as state.
• Answers "does this subscriber have this access level?" from a local copy of RevenueCat's subscriptions and purchases, plus grants your app issues.
• Issues grants — trials, earned days, support grants — each with a source, an expiry and an idempotency key, so one share can never award days twice.
• Announces changes: access gained or lost, renewals, billing problems, refunds.
• Optional extras: an access guard for your resolvers, and two end-user GraphQL operations the Flutter package can call.

What stays in your app

Paywall screens and prices, what each access level unlocks, earning rules and caps, admin roles and audit, authentication, and scheduling. The package holds the subscription logic and nothing else.

Design

• Interface-driven persistence. Your app passes repositories in, or takes the Prisma adapter from the /prisma entry point if you use the reference schema.
• RevenueCat is the authority on paid access. Nothing computes an expiry by adding days.
• No dependency on other packages. The subscriber is an opaque ID your app supplies, so the package never dictates your auth.

Entry points

| Import | Contents | |---|---| | @ambushsoftworks/nestjs-subscriptions | The module, services, GraphQL models, decorators, exceptions, ports | | …/prisma | Prisma repositories and transaction manager for the reference schema | | …/testing | Conformance kit, in-memory repositories, RevenueCat test double |

Exceptions

Every exception extends SubscriptionException and carries a stable .code. The codes are public API: map them to your own GraphQL or HTTP errors. They do not change without a major version.

| Exception | .code | Thrown when | |---|---|---| | UniqueConstraintViolationException | UNIQUE_CONSTRAINT_VIOLATION | An adapter translated its ORM's unique violation. The package adopts the winning row rather than failing | | SubscriptionsConfigurationException | SUBSCRIPTIONS_CONFIGURATION | The module was configured in a way that cannot work. Thrown at boot | | NoSubscriberException | NO_SUBSCRIBER | No subscriber could be resolved from the request | | AccessRequiredException | ACCESS_REQUIRED | The caller lacks the entitlement a guarded operation requires | | InvalidSubscriberIdException | INVALID_SUBSCRIBER_ID | A subscriber ID RevenueCat would reject as an App User ID | | UnknownEntitlementException | UNKNOWN_ENTITLEMENT | An entitlement that is not in the configured list | | UnknownGrantSourceException | UNKNOWN_GRANT_SOURCE | A grant source that is not in the configured list | | InvalidGrantException | INVALID_GRANT | A grant whose length is missing, doubly specified, or already over | | GrantNotFoundException | GRANT_NOT_FOUND | A grant that does not exist, or belongs to another subscriber | | RevenueCatUnavailableException | REVENUECAT_UNAVAILABLE | RevenueCat could not be reached, or answered with an error. A webhook failing this way answers non-200 so RevenueCat retries | | RevenueCatRateLimitedException | REVENUECAT_RATE_LIMITED | RevenueCat rate-limited the request. Carries retryAfterSeconds | | WebhookUnauthorizedException | WEBHOOK_UNAUTHORIZED | A webhook whose authorization value or signature did not match |

Reserved GraphQL names

Importing SubscriptionsGraphQLModule registers these type names. An app that declares its own type with any of them crashes at schema build with "type already registered", so rename yours or leave the optional module out.

| Name | Kind | |---|---| | SubscriptionAccessStatus | object type | | SubscriptionAccessSource | object type | | StorePurchaseKind | enum | | AccessSourceType | enum |

License

MIT © Ambush Softworks