@farm.js/polar 0.1.50 → 0.1.51-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +109 -3
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,11 +1,117 @@
1
1
  # @farm.js/polar
2
2
 
3
- Polar billing integration for Farm.js
3
+ Polar billing for Farm.js applications. The integration mounts typed routes for the product
4
+ catalog, Polar checkout, the customer portal, and billing status, entitlement, and usage checks.
5
+ Billing state is read from Polar for each owner, so the integration keeps no local billing tables.
4
6
 
5
7
  See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
6
8
 
9
+ ## Install
10
+
7
11
  ```bash
8
- npm install @farm.js/polar
12
+ pnpm add @farm.js/polar
13
+ ```
14
+
15
+ `@polar-sh/sdk` is a dependency and installs with the package. To scaffold the registry entry and a
16
+ pricing page at `/integrations/polar` in an existing app, run `farm add integration polar --ui`.
17
+
18
+ ## Configure
19
+
20
+ `billing` is required, and its `resolveOwner` decides who the signed-in caller bills as.
21
+
22
+ ```ts
23
+ // src/lib/integrations.ts
24
+ import { polar } from "@farm.js/polar";
25
+ import { getUser } from "./session";
26
+
27
+ export const appIntegrations = {
28
+ billing: polar({
29
+ billing: {
30
+ async resolveOwner(ctx) {
31
+ const user = await getUser(ctx.request);
32
+ return user ? { kind: "user", id: user.id, email: user.email } : null;
33
+ },
34
+ plans: {
35
+ pro: { features: { analytics: true }, limits: { tokensMonthly: 1_000_000 } },
36
+ },
37
+ products: {
38
+ proMonthly: {
39
+ kind: "subscription",
40
+ planId: "pro",
41
+ polar: { productId: process.env.POLAR_PRO_MONTHLY_PRODUCT_ID },
42
+ },
43
+ },
44
+ },
45
+ }),
46
+ } as const;
47
+ ```
48
+
49
+ | Variable | Purpose |
50
+ | ---------------------- | ---------------------------------------------------------------------------- |
51
+ | `POLAR_ACCESS_TOKEN` | Builds the Polar client. Required unless `instance` or `accessToken` is set. |
52
+ | `POLAR_SERVER` | `sandbox` or `production`. Defaults to `sandbox`. |
53
+ | `POLAR_WEBHOOK_SECRET` | Default secret for the webhook route. |
54
+ | `APP_BASE_URL` | Origin for checkout and portal return URLs. Defaults to the request origin. |
55
+
56
+ `accessToken`, `server`, and `appBaseUrl` override the environment. Pass an app-owned `Polar` client
57
+ as `instance` to keep SDK construction in application code.
58
+
59
+ ## Customers
60
+
61
+ Each owner is a `"user"` or an `"organization"` and maps to one Polar customer by external id. The
62
+ id is `<kind>:<id>`, such as `user:42`, unless `billing.resolveExternalCustomerId` returns another.
63
+
64
+ ## Routes
65
+
66
+ Routes mount under `/billing`: `products`, `status`, `current-charges`, `features`, `limits`,
67
+ `usage`, `meter-usage`, `report-usage`, `check`, `checkout`, and `portal`. Each has a matching
68
+ option, such as `checkoutPath`, to move it. Call them through `createIntegrations`:
69
+
70
+ ```ts
71
+ const checkout = await apiClient.billing.checkout({
72
+ body: { productId: "proMonthly", successPath: "/billing/success" },
73
+ });
9
74
  ```
10
75
 
11
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
76
+ The routes act for the caller from its cookies, so requests from other origins are refused unless
77
+ listed in `allowedOrigins`.
78
+
79
+ A meter needs an `eventName` and a `polar.meterId`. `polar()` throws at startup when either is
80
+ missing. Reported usage is sent to Polar as events, and `hooks.onUsageReported` runs after each one.
81
+
82
+ ## Webhooks
83
+
84
+ The webhook route mounts only when `webhooks` is set:
85
+
86
+ ```ts
87
+ polar({
88
+ webhooks: {
89
+ async onEvent(event) {
90
+ console.log(event.type, event.id);
91
+ },
92
+ },
93
+ billing,
94
+ });
95
+ ```
96
+
97
+ - The path defaults to `/billing/webhook` and the secret to `POLAR_WEBHOOK_SECRET`.
98
+ - The object needs at least one of `path`, `secret`, `onEvent`, or `onError`. An empty `{}` mounts
99
+ nothing.
100
+ - For several endpoints, pass named definitions, each with its own `path`.
101
+ - The route verifies the signature and calls `onEvent`. It changes no billing state itself, since
102
+ status is always read from Polar. A bad signature gets `403`, and `onError` can return a response
103
+ of its own.
104
+
105
+ ## Client entry
106
+
107
+ `@farm.js/polar/client` exports `polarClient`, `createPolarClientApi`, and the request and response
108
+ types without loading the Polar SDK, so browser code can import it.
109
+
110
+ ## Documentation
111
+
112
+ - [Polar integration](https://farmjs.dev/docs/integrations/polar)
113
+ - [`examples/polar-integration`](https://github.com/farming-labs/farm.js/tree/main/examples/polar-integration)
114
+ bills Better Auth organizations, with metered usage and webhooks
115
+
116
+ Report issues and find examples in the
117
+ [Farm.js repository](https://github.com/farming-labs/farm.js).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@farm.js/polar",
3
- "version": "0.1.50",
3
+ "version": "0.1.51-beta.0",
4
4
  "description": "Polar billing integration for Farm.js",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -30,8 +30,8 @@
30
30
  },
31
31
  "dependencies": {
32
32
  "@polar-sh/sdk": "^0.47.0",
33
- "@farm.js/core": "0.1.50",
34
- "@farm.js/integration-utils": "0.1.50"
33
+ "@farm.js/integration-utils": "0.1.51-beta.0",
34
+ "@farm.js/core": "0.1.51-beta.0"
35
35
  },
36
36
  "scripts": {
37
37
  "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",