@farm.js/polar 0.1.49 → 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.
- package/README.md +109 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,11 +1,117 @@
|
|
|
1
1
|
# @farm.js/polar
|
|
2
2
|
|
|
3
|
-
Polar billing
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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/integration-utils": "0.1.
|
|
34
|
-
"@farm.js/core": "0.1.
|
|
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",
|