finget-sdk 1.0.0 → 1.0.2
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 +176 -36
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,33 +1,78 @@
|
|
|
1
|
-
# finget
|
|
1
|
+
# finget-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/finget-sdk)
|
|
4
|
+
[](https://www.npmjs.com/package/finget-sdk)
|
|
5
|
+
[](LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
- مستندات API: [finget.ir/provider/panel/docs](https://finget.ir/provider/panel/docs)
|
|
7
|
-
- دانلود ZIP: [finget.ir/plugins](https://finget.ir/plugins)
|
|
7
|
+
Official **Node.js** SDK for the [Finget](https://finget.ir) public API (`/api/v1`).
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Written in TypeScript, published as ESM + CommonJS with full `.d.ts` typings. Use it from TypeScript or plain JavaScript on the server.
|
|
10
|
+
|
|
11
|
+
- Passwordless **Sign in with Finget**
|
|
12
|
+
- Exchange callback `code` for a Finget user
|
|
13
|
+
- Send **push notifications** to linked users
|
|
14
|
+
- Check site and notification status
|
|
15
|
+
|
|
16
|
+
> Keep your API key on the server only. Never ship `FINGET_API_KEY` to the browser.
|
|
17
|
+
|
|
18
|
+
## Links
|
|
19
|
+
|
|
20
|
+
| | |
|
|
21
|
+
|---|---|
|
|
22
|
+
| Website | [finget.ir](https://finget.ir) |
|
|
23
|
+
| Plugins & SDKs | [finget.ir/plugins](https://finget.ir/plugins) |
|
|
24
|
+
| API docs | [Provider panel docs](https://finget.ir/provider/panel/docs) |
|
|
25
|
+
| npm | [finget-sdk](https://www.npmjs.com/package/finget-sdk) |
|
|
26
|
+
| Repository | [amirsafaridevs/finget-js](https://github.com/amirsafaridevs/finget-js) |
|
|
27
|
+
|
|
28
|
+
## Requirements
|
|
29
|
+
|
|
30
|
+
- **Node.js 18+** (uses native `fetch` and `crypto.getRandomValues`)
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
10
33
|
|
|
11
34
|
```bash
|
|
12
35
|
npm install finget-sdk
|
|
13
36
|
```
|
|
14
37
|
|
|
15
|
-
|
|
38
|
+
```bash
|
|
39
|
+
pnpm add finget-sdk
|
|
40
|
+
yarn add finget-sdk
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Quick start
|
|
16
44
|
|
|
17
45
|
```bash
|
|
18
46
|
export FINGET_API_KEY=fg_live_...
|
|
19
47
|
```
|
|
20
48
|
|
|
49
|
+
### TypeScript / ESM
|
|
50
|
+
|
|
21
51
|
```ts
|
|
22
52
|
import { Client } from "finget-sdk";
|
|
23
53
|
|
|
24
54
|
const finget = Client.fromEnv();
|
|
25
|
-
//
|
|
55
|
+
// or: new Client({ apiKey: process.env.FINGET_API_KEY! })
|
|
26
56
|
|
|
27
57
|
const { site } = await finget.getSite();
|
|
58
|
+
console.log(site.domain, site.displayDomain);
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### CommonJS
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
const { Client } = require("finget-sdk");
|
|
65
|
+
|
|
66
|
+
const finget = new Client({ apiKey: process.env.FINGET_API_KEY });
|
|
28
67
|
```
|
|
29
68
|
|
|
30
|
-
##
|
|
69
|
+
## Authentication (Sign in with Finget)
|
|
70
|
+
|
|
71
|
+
1. In the Finget provider panel, copy your **site client ID** and register the callback URL.
|
|
72
|
+
2. Redirect the user to Finget with a CSRF `state` stored in the session.
|
|
73
|
+
3. On callback, verify `state`, then exchange `code`.
|
|
74
|
+
|
|
75
|
+
Example with Express-style handlers:
|
|
31
76
|
|
|
32
77
|
```ts
|
|
33
78
|
import { Client } from "finget-sdk";
|
|
@@ -35,45 +80,138 @@ import { Client } from "finget-sdk";
|
|
|
35
80
|
const finget = Client.fromEnv();
|
|
36
81
|
const clientId = process.env.FINGET_CLIENT_ID!;
|
|
37
82
|
|
|
38
|
-
//
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
const expected = req.session.fingetState;
|
|
45
|
-
delete req.session.fingetState;
|
|
46
|
-
if (!req.query.code || !expected || req.query.state !== expected) {
|
|
47
|
-
return res.redirect("/login");
|
|
48
|
-
}
|
|
83
|
+
// GET /login/finget
|
|
84
|
+
app.get("/login/finget", (req, res) => {
|
|
85
|
+
const { url, state } = finget.loginUrl(clientId);
|
|
86
|
+
req.session.fingetState = state;
|
|
87
|
+
res.redirect(url);
|
|
88
|
+
});
|
|
49
89
|
|
|
50
|
-
|
|
51
|
-
|
|
90
|
+
// GET /auth/finget/callback
|
|
91
|
+
app.get("/auth/finget/callback", async (req, res) => {
|
|
92
|
+
const expected = req.session.fingetState;
|
|
93
|
+
delete req.session.fingetState;
|
|
94
|
+
|
|
95
|
+
const code = String(req.query.code ?? "");
|
|
96
|
+
const state = String(req.query.state ?? "");
|
|
97
|
+
|
|
98
|
+
if (!code || !expected || state !== expected) {
|
|
99
|
+
return res.redirect("/login");
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
const { user, isNew } = await finget.exchangeCode(code);
|
|
103
|
+
// user: { id, name, phone }
|
|
104
|
+
// Find or create your local account by user.id, then establish a session.
|
|
105
|
+
res.redirect("/");
|
|
106
|
+
});
|
|
52
107
|
```
|
|
53
108
|
|
|
54
|
-
|
|
109
|
+
### `loginUrl()`
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
const { url, state } = finget.loginUrl(clientId);
|
|
113
|
+
const { url, state } = finget.loginUrl(clientId, existingState);
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Notifications
|
|
55
117
|
|
|
56
118
|
```ts
|
|
57
119
|
await finget.sendNotification({
|
|
58
|
-
id: `order-${order.id}-shipped`,
|
|
59
|
-
kind: "notice",
|
|
60
|
-
title: "
|
|
61
|
-
body:
|
|
62
|
-
link: {
|
|
120
|
+
id: `order-${order.id}-shipped`, // optional idempotency key
|
|
121
|
+
kind: "notice", // "notice" | "reminder" | "security" | "promo"
|
|
122
|
+
title: "Your order shipped",
|
|
123
|
+
body: `Order ${order.id} is on the way.`,
|
|
124
|
+
link: {
|
|
125
|
+
url: `https://shop.example/orders/${order.id}`,
|
|
126
|
+
label: "Track order",
|
|
127
|
+
},
|
|
63
128
|
users: [user.fingetId],
|
|
129
|
+
// or: audience: "all",
|
|
64
130
|
});
|
|
65
131
|
```
|
|
66
132
|
|
|
67
|
-
|
|
133
|
+
Optional coupon:
|
|
68
134
|
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
|
|
135
|
+
```ts
|
|
136
|
+
coupon: {
|
|
137
|
+
code: "SAVE10",
|
|
138
|
+
note: "Valid this week",
|
|
139
|
+
expiresAt: "2026-12-31T23:59:59+03:30",
|
|
140
|
+
}
|
|
141
|
+
```
|
|
72
142
|
|
|
73
|
-
|
|
143
|
+
Check status:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
const status = await finget.getNotification("order-1234-shipped");
|
|
74
147
|
```
|
|
75
148
|
|
|
76
|
-
##
|
|
149
|
+
## API reference
|
|
150
|
+
|
|
151
|
+
### `Client`
|
|
152
|
+
|
|
153
|
+
| Method | Description |
|
|
154
|
+
|--------|-------------|
|
|
155
|
+
| `Client.fromEnv(apiKeyEnv?: string)` | Build from `process.env` (default key: `FINGET_API_KEY`) |
|
|
156
|
+
| `getSite()` | Validate the API key; return `{ site }` |
|
|
157
|
+
| `loginUrl(clientId, state?)` | Auth redirect URL + state |
|
|
158
|
+
| `createState(bytes?)` | Secure random hex state (default 16 bytes) |
|
|
159
|
+
| `exchangeCode(code)` | Exchange callback code → `{ user, isNew }` |
|
|
160
|
+
| `getUser(userId)` | Refresh a linked user → `{ user }` |
|
|
161
|
+
| `sendNotification(payload)` | Create a notification (expects HTTP 201) |
|
|
162
|
+
| `getNotification(notificationId)` | Notification status payload |
|
|
163
|
+
|
|
164
|
+
### Constructor options
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
new Client({
|
|
168
|
+
apiKey: string; // required — fg_live_…
|
|
169
|
+
baseUrl?: string; // default https://finget.ir/api/v1
|
|
170
|
+
authUrl?: string; // default https://finget.ir/auth
|
|
171
|
+
timeoutMs?: number; // default 20_000
|
|
172
|
+
});
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Environment variables
|
|
176
|
+
|
|
177
|
+
| Variable | Required | Description |
|
|
178
|
+
|----------|----------|-------------|
|
|
179
|
+
| `FINGET_API_KEY` | yes (for `fromEnv`) | Site API key |
|
|
180
|
+
| `FINGET_BASE_URL` | no | Override API base URL |
|
|
181
|
+
| `FINGET_AUTH_URL` | no | Override login page URL |
|
|
182
|
+
|
|
183
|
+
### Types (TypeScript)
|
|
184
|
+
|
|
185
|
+
Exported from `finget-sdk`:
|
|
186
|
+
|
|
187
|
+
- `ClientOptions`
|
|
188
|
+
- `FingetUser` — `{ id, name, phone }`
|
|
189
|
+
- `SiteInfo`
|
|
190
|
+
- `TokenResult` — `{ user, isNew }`
|
|
191
|
+
- `SendNotificationInput`
|
|
192
|
+
- `NotificationResult`
|
|
193
|
+
- `NotificationLink`, `NotificationCoupon`
|
|
194
|
+
|
|
195
|
+
### Errors
|
|
196
|
+
|
|
197
|
+
```ts
|
|
198
|
+
import { Client, ApiError, FingetError } from "finget-sdk";
|
|
199
|
+
|
|
200
|
+
try {
|
|
201
|
+
await Client.fromEnv().getSite();
|
|
202
|
+
} catch (err) {
|
|
203
|
+
if (err instanceof ApiError) {
|
|
204
|
+
err.message;
|
|
205
|
+
err.status; // 0 if network / timeout
|
|
206
|
+
err.errorCode; // e.g. invalid_api_key when present
|
|
207
|
+
err.body;
|
|
208
|
+
} else if (err instanceof FingetError) {
|
|
209
|
+
// Client-side validation
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
## Local development
|
|
77
215
|
|
|
78
216
|
```ts
|
|
79
217
|
const finget = new Client({
|
|
@@ -83,6 +221,8 @@ const finget = new Client({
|
|
|
83
221
|
});
|
|
84
222
|
```
|
|
85
223
|
|
|
86
|
-
|
|
224
|
+
Or set `FINGET_BASE_URL` / `FINGET_AUTH_URL` in the environment before `Client.fromEnv()`.
|
|
225
|
+
|
|
226
|
+
## License
|
|
87
227
|
|
|
88
|
-
MIT
|
|
228
|
+
[MIT](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "finget-sdk",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"description": "Official Node.js / JavaScript / TypeScript SDK for the Finget passwordless login and notification API",
|
|
5
5
|
"license": "MIT",
|
|
6
|
-
"author":
|
|
7
|
-
|
|
6
|
+
"author": {
|
|
7
|
+
"name": "Finget",
|
|
8
|
+
"url": "https://finget.ir"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://finget.ir",
|
|
8
11
|
"repository": {
|
|
9
12
|
"type": "git",
|
|
10
13
|
"url": "git+https://github.com/amirsafaridevs/finget-js.git"
|