finget-sdk 1.0.1 → 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.
Files changed (2) hide show
  1. package/README.md +175 -37
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,35 +1,78 @@
1
1
  # finget-sdk
2
2
 
3
- کلاینت رسمی **[فینگت](https://finget.ir)** برای **Node.js**، **JavaScript** و **TypeScript**: ورود بدون رمز و ارسال اعلان.
3
+ [![npm](https://img.shields.io/npm/v/finget-sdk.svg)](https://www.npmjs.com/package/finget-sdk)
4
+ [![Node](https://img.shields.io/node/v/finget-sdk.svg)](https://www.npmjs.com/package/finget-sdk)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
6
 
5
- - وب‌سایت: [finget.ir](https://finget.ir)
6
- - افزونه‌ها و SDKها: [finget.ir/plugins](https://finget.ir/plugins)
7
- - مستندات API: [finget.ir/provider/panel/docs](https://finget.ir/provider/panel/docs)
8
- - npm: [npmjs.com/package/finget-sdk](https://www.npmjs.com/package/finget-sdk)
9
- - نیازمندی: **Node.js 18+** (native `fetch`)
7
+ Official **Node.js** SDK for the [Finget](https://finget.ir) public API (`/api/v1`).
10
8
 
11
- ## نصب
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
12
33
 
13
34
  ```bash
14
35
  npm install finget-sdk
15
36
  ```
16
37
 
17
- ## شروع سریع
38
+ ```bash
39
+ pnpm add finget-sdk
40
+ yarn add finget-sdk
41
+ ```
42
+
43
+ ## Quick start
18
44
 
19
45
  ```bash
20
46
  export FINGET_API_KEY=fg_live_...
21
47
  ```
22
48
 
49
+ ### TypeScript / ESM
50
+
23
51
  ```ts
24
52
  import { Client } from "finget-sdk";
25
53
 
26
54
  const finget = Client.fromEnv();
27
- // یا: new Client({ apiKey: process.env.FINGET_API_KEY! })
55
+ // or: new Client({ apiKey: process.env.FINGET_API_KEY! })
28
56
 
29
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 });
30
67
  ```
31
68
 
32
- ## ورود با فینگت
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:
33
76
 
34
77
  ```ts
35
78
  import { Client } from "finget-sdk";
@@ -37,45 +80,138 @@ import { Client } from "finget-sdk";
37
80
  const finget = Client.fromEnv();
38
81
  const clientId = process.env.FINGET_CLIENT_ID!;
39
82
 
40
- // شروع ورود
41
- const { url, state } = finget.loginUrl(clientId);
42
- req.session.fingetState = state;
43
- res.redirect(url);
44
-
45
- // callback
46
- const expected = req.session.fingetState;
47
- delete req.session.fingetState;
48
- if (!req.query.code || !expected || req.query.state !== expected) {
49
- return res.redirect("/login");
50
- }
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
+ });
51
89
 
52
- const { user, isNew } = await finget.exchangeCode(String(req.query.code));
53
- // حساب را با user.id پیدا یا بسازید
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
+ });
54
107
  ```
55
108
 
56
- ## ارسال اعلان
109
+ ### `loginUrl()`
110
+
111
+ ```ts
112
+ const { url, state } = finget.loginUrl(clientId);
113
+ const { url, state } = finget.loginUrl(clientId, existingState);
114
+ ```
115
+
116
+ ## Notifications
57
117
 
58
118
  ```ts
59
119
  await finget.sendNotification({
60
- id: `order-${order.id}-shipped`,
61
- kind: "notice",
62
- title: "سفارش شما ارسال شد",
63
- body: `سفارش ${order.id} تحویل پست شد.`,
64
- link: { url: `https://shop.ir/orders/${order.id}`, label: "پیگیری سفارش" },
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
+ },
65
128
  users: [user.fingetId],
129
+ // or: audience: "all",
66
130
  });
67
131
  ```
68
132
 
69
- ## JavaScript (بدون TypeScript)
133
+ Optional coupon:
70
134
 
71
- ```js
72
- const { Client } = require("finget-sdk");
73
- // یا: import { Client } from "finget-sdk";
135
+ ```ts
136
+ coupon: {
137
+ code: "SAVE10",
138
+ note: "Valid this week",
139
+ expiresAt: "2026-12-31T23:59:59+03:30",
140
+ }
141
+ ```
74
142
 
75
- const finget = new Client({ apiKey: process.env.FINGET_API_KEY });
143
+ Check status:
144
+
145
+ ```ts
146
+ const status = await finget.getNotification("order-1234-shipped");
76
147
  ```
77
148
 
78
- ## توسعهٔ محلی
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
79
215
 
80
216
  ```ts
81
217
  const finget = new Client({
@@ -85,6 +221,8 @@ const finget = new Client({
85
221
  });
86
222
  ```
87
223
 
88
- ## مجوز
224
+ Or set `FINGET_BASE_URL` / `FINGET_AUTH_URL` in the environment before `Client.fromEnv()`.
225
+
226
+ ## License
89
227
 
90
- MIT
228
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "finget-sdk",
3
- "version": "1.0.1",
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
6
  "author": {