Skip to content

Commit e66a47b

Browse files
tolgaozentolgaozen
authored
Merge pull request #282 from thisisnkc/chore/update-readme
chore: updated readme
2 parents 8c60d08 + ef3e490 commit e66a47b

File tree

2 files changed

+183
-93
lines changed

2 files changed

+183
-93
lines changed

‎README.md‎

Lines changed: 182 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,16 @@
1414
<a href="https://discord.gg/MJbUjwskdH" target="_blank"><img src="https://img.shields.io/discord/950799928047833088?style=for-the-badge&logo=discord&label=DISCORD" alt="Permify Discord Channel" /></a>&nbsp;
1515
</p>
1616

17-
This client makes it easy to interact with [Permify](https://github.com/Permify/permify) from your Node.js application.
17+
This client makes it easy to interact with [Permify](https://github.com/Permify/permify) from your Node.js application, providing type-safe access to Permify's authorization capabilities.
18+
19+
## Features
20+
21+
- Full TypeScript support
22+
- Promise-based API
23+
- Support for all Permify gRPC endpoints
24+
- Built-in error handling
25+
- Interceptor support for authentication and logging
26+
- Streaming support for real-time updates
1827

1928
# Installation
2029

@@ -30,37 +39,64 @@ Use yarn to install (Please be aware that Yarn versions greater than v1.10.0 and
3039
yarn add @permify/permify-node
3140
```
3241

33-
# How to use
42+
# Getting Started
43+
44+
## Prerequisites
45+
46+
- Node.js 14.x or later
47+
- A running instance of Permify server (local or cloud)
48+
- Basic understanding of Permify's authorization model
3449

35-
### Create a new tenant
50+
## Basic Usage
51+
52+
### 1. Initialize the Client
53+
54+
First, create a new client instance to connect to your Permify server:
3655

3756
```typescript
3857
import * as permify from "@permify/permify-node";
3958

4059
const client = permify.grpc.newClient({
41-
endpoint: "localhost:3478",
42-
cert: undefined,
43-
insecure: true
60+
endpoint: "localhost:3478", // Replace with your Permify server URL
61+
cert: undefined, // Optional: SSL certificate
62+
insecure: true, // Set to false in production
63+
timeout: 5000, // Request timeout in milliseconds
4464
});
65+
```
4566

46-
client.tenancy.create({
67+
### 2. Tenant Management
68+
69+
```typescript
70+
import * as permify from "@permify/permify-node";
71+
72+
const client = permify.grpc.newClient({
73+
endpoint: "localhost:3478",
74+
cert: undefined,
75+
insecure: true,
76+
});
77+
78+
client.tenancy
79+
.create({
4780
id: "t1",
48-
name: "Tenant 1"
49-
}).then((response) => {
81+
name: "Tenant 1",
82+
})
83+
.then((response) => {
5084
console.log(response);
5185
// handle response
52-
})
86+
});
5387
```
5488

55-
### Write Schema
89+
### 3. Schema Management
90+
91+
Define your authorization model using Permify's schema language. Here's a more comprehensive example:
5692

5793
```typescript
5894
import * as permify from "@permify/permify-node";
5995

6096
const client = permify.grpc.newClient({
61-
endpoint: "localhost:3478",
62-
cert: undefined,
63-
insecure: true
97+
endpoint: "localhost:3478",
98+
cert: undefined,
99+
insecure: true,
64100
});
65101

66102
let schema = `
@@ -74,155 +110,209 @@ let schema = `
74110
`;
75111

76112
// Write the schema
77-
client.tenancy.create({
113+
client.tenancy
114+
.create({
78115
tenantId: "t1",
79-
schema: schema
80-
}).then((response) => {
116+
schema: schema,
117+
})
118+
.then((response) => {
81119
// handle response
82-
})
120+
});
83121
```
84122

85-
### Write Relationships
123+
### 4. Relationship Management
124+
125+
Create relationships between entities to define access rules. Here are some common patterns:
86126

87127
```typescript
88128
import * as permify from "@permify/permify-node";
89129

90130
const client = permify.grpc.newClient({
91-
endpoint: "localhost:3478",
92-
cert: undefined,
93-
insecure: true
131+
endpoint: "localhost:3478",
132+
cert: undefined,
133+
insecure: true,
94134
});
95135

96-
client.relationship.write({
136+
client.relationship
137+
.write({
97138
tenantId: "t1",
98139
metadata: {
99-
schemaVersion: ""
140+
schemaVersion: "",
100141
},
101-
tuples: [{
142+
tuples: [
143+
{
102144
entity: {
103-
type: "document",
104-
id: "1"
145+
type: "document",
146+
id: "1",
105147
},
106148
relation: "viewer",
107149
subject: {
108-
type: "user",
109-
id: "1"
110-
}
111-
}]
112-
}).then((response) => {
150+
type: "user",
151+
id: "1",
152+
},
153+
},
154+
],
155+
})
156+
.then((response) => {
113157
// handle response
114-
})
158+
});
115159
```
116160

117-
### Check
161+
### 5. Permission Checks
162+
163+
Verify if a user has a specific permission on a resource. Here are different ways to perform checks:
118164

119165
```typescript
120166
import * as permify from "@permify/permify-node";
121167

122168
const client = permify.grpc.newClient({
123-
endpoint: "localhost:3478",
124-
cert: undefined,
125-
insecure: true
169+
endpoint: "localhost:3478",
170+
cert: undefined,
171+
insecure: true,
126172
});
127173

128-
client.permission.check({
174+
client.permission
175+
.check({
129176
tenantId: "t1",
130177
metadata: {
131-
snapToken: "",
132-
schemaVersion: "",
133-
depth: 20
178+
snapToken: "",
179+
schemaVersion: "",
180+
depth: 20,
134181
},
135182
entity: {
136-
type: "document",
137-
id: "1"
183+
type: "document",
184+
id: "1",
138185
},
139186
permission: "view",
140187
subject: {
141-
type: "user",
142-
id: "3"
143-
}
144-
}).then((response) => {
188+
type: "user",
189+
id: "3",
190+
},
191+
})
192+
.then((response) => {
145193
if (response.can === permify.grpc.base.CheckResult.CHECK_RESULT_ALLOWED) {
146-
console.log("RESULT_ALLOWED")
194+
console.log("RESULT_ALLOWED");
147195
} else {
148-
console.log("RESULT_DENIED")
196+
console.log("RESULT_DENIED");
149197
}
150-
})
198+
});
151199
```
152200

153-
### Streaming Calls
201+
## Advanced Usage
202+
203+
### 1. Real-time Updates with Streaming
204+
205+
Subscribe to permission changes in real-time:
154206

155207
```typescript
156208
import * as permify from "@permify/permify-node";
157209

158210
function main() {
159-
const client = permify.grpc.newClient({
160-
endpoint: "localhost:3478",
161-
cert: undefined,
162-
insecure: true
163-
});
164-
165-
let res = client.permission.lookupEntityStream({
166-
tenantId: "t1",
167-
metadata: {
168-
snapToken: "",
169-
schemaVersion: "",
170-
depth: 20
171-
},
172-
entityType: "document",
173-
permission: "view",
174-
subject: {
175-
type: "user",
176-
id: "1"
177-
}
178-
})
211+
const client = permify.grpc.newClient({
212+
endpoint: "localhost:3478",
213+
cert: undefined,
214+
insecure: true,
215+
});
216+
217+
let res = client.permission.lookupEntityStream({
218+
tenantId: "t1",
219+
metadata: {
220+
snapToken: "",
221+
schemaVersion: "",
222+
depth: 20,
223+
},
224+
entityType: "document",
225+
permission: "view",
226+
subject: {
227+
type: "user",
228+
id: "1",
229+
},
230+
});
179231

180-
handle(res)
232+
handle(res);
181233
}
182234

183-
async function handle(res: AsyncIterable<permify.grpc.payload.PermissionLookupEntityStreamResponse>) {
184-
for await (const response of res) {
185-
// response.entityId
186-
}
235+
async function handle(
236+
res: AsyncIterable<permify.grpc.payload.PermissionLookupEntityStreamResponse>
237+
) {
238+
for await (const response of res) {
239+
// response.entityId
240+
}
187241
}
188242
```
189243

190-
### Interceptors
244+
### 2. Interceptors
191245

192-
#### Access Token Interceptor
246+
#### Access Token Interceptor:
193247

194248
```typescript
195249
import * as permify from "@permify/permify-node";
196250

197-
const client = new permify.grpc.newClient({
251+
const client = new permify.grpc.newClient(
252+
{
198253
endpoint: "localhost:3478",
199254
cert: undefined,
200-
insecure: true
201-
}, permify.grpc.newAccessTokenInterceptor("YOUR_TOKEN"))
255+
insecure: true,
256+
},
257+
permify.grpc.newAccessTokenInterceptor("YOUR_TOKEN")
258+
);
202259
```
203260

204261
### Certs
205262

206263
```typescript
207264
import * as permify from "@permify/permify-node";
208-
import fs from 'fs';
265+
import fs from "fs";
209266

210-
const cert = fs.readFileSync('path/to/cert.pem');
267+
const cert = fs.readFileSync("path/to/cert.pem");
211268

212-
const client = new permify.grpc.newClient({
269+
const client = new permify.grpc.newClient(
270+
{
213271
endpoint: "localhost:3478",
214272
cert: cert,
215-
insecure: true
216-
}, permify.grpc.newAccessTokenInterceptor("YOUR_TOKEN"))
273+
insecure: true,
274+
},
275+
permify.grpc.newAccessTokenInterceptor("YOUR_TOKEN")
276+
);
217277
```
218278

219-
Permify is an **open-source authorization service** for creating and maintaining fine-grained authorizations accross
220-
your individual applications and services.
279+
## Error Handling
280+
281+
All API calls return Promises that can be handled with try/catch:
282+
283+
```typescript
284+
try {
285+
const response = await client.tenancy.create({
286+
id: "t1",
287+
name: "Production Tenant",
288+
});
289+
console.log("Tenant created:", response);
290+
} catch (error) {
291+
console.error("Error creating tenant:", error);
292+
// Handle specific error types
293+
if (error.code === grpc.status.ALREADY_EXISTS) {
294+
console.log("Tenant already exists");
295+
}
296+
}
297+
```
298+
299+
## Resources
300+
301+
- [Permify Website](https://permify.co)
302+
- [Comprehensive Documentation](https://docs.permify.co/docs)
303+
- [API Reference](https://docs.permify.co/docs/api-overview)
304+
- [GitHub Repository](https://github.com/Permify/permify)
305+
306+
## Contributing
307+
308+
Contributions are welcome! Please read our [contributing guidelines](https://github.com/Permify/permify-node/CONTRIBUTING.md) to get started.
309+
310+
## License
311+
312+
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
221313

222-
* [Permify website](https://permify.co)
223-
* [Permify documentation](https://docs.permify.co/docs)
224-
* [Permify playground](https://play.permify.co)
225-
* [Permify GitHub Repository](https://github.com/Permify/permify)
314+
- [Permify playground](https://play.permify.co)
315+
- [Permify GitHub Repository](https://github.com/Permify/permify)
226316

227317
## Community & Support
228318

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@permify/permify-node",
3-
"version": "1.0.8",
3+
"version": "1.0.9",
44
"description": "Permify Node Client",
55
"main": "dist/src/index.js",
66
"types": "dist/src/index.d.ts",

0 commit comments

Comments
 (0)