feat: support list users (#97)

Author: rhamzeh

.github/dependabot.yaml

@@ -8,8 +8,6 @@ updates:
      dependencies:
         patterns:
           - "*"
-        exclude-patterns:
-          - "eslint"
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
@@ -18,3 +16,5 @@ updates:
      dependencies:
         patterns:
           - "*"
+        exclude-patterns:
+          - "eslint"

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.4.0
+
+### [0.4.0](https://github.com/openfga/js-sdk/compare/v0.3.5...v0.4.0) (2024-04-30)
+
+- feat: support the [ListUsers](https://github.com/openfga/rfcs/blob/main/20231214-listUsers-api.md) endpoint (#97)
+- feat!: support overriding storeId per request (#97)
+    `OpenFgaClient` now supports specifying the storeId in the options to override it per request
+
+    [BREAKING CHANGE] the underlying `OpenFgaApi` now expects `storeId` as the first param on relevant methods,
+    if you are still using this class, make sure you update your references when needed.
+
 ## v0.3.5
 
 ### [0.3.5](https://github.com/openfga/js-sdk/compare/v0.3.4...v0.3.5) (2024-03-19)

README.md

@@ -38,6 +38,7 @@ This is an autogenerated JavaScript SDK for OpenFGA. It provides a wrapper aroun
       - [Expand](#expand)
       - [List Objects](#list-objects)
       - [List Relations](#list-relations)
+      - [List Users](#list-users)
     - [Assertions](#assertions)
       - [Read Assertions](#read-assertions)
       - [Write Assertions](#write-assertions)
@@ -97,7 +98,7 @@ const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required
   storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
-  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID, // Optional, can be overridden per request
+  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
 });
 ```
 
@@ -109,7 +110,7 @@ const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required
   storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
-  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID, // Optional, can be overridden per request
+  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
   credentials: {
     method: CredentialsMethod.ApiToken,
     config: {
@@ -127,7 +128,7 @@ const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required
   storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
-  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID, // Optional, can be overridden per request
+  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
   credentials: {
     method: CredentialsMethod.ClientCredentials,
     config: {
@@ -462,7 +463,7 @@ const { responses } = await fgaClient.batchCheck([{
   user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
   relation: "viewer",
   object: "document:roadmap",
-  contextualTuples: [{
+  contextual_tuples: [{
     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation: "writer",
     object: "document:roadmap"
@@ -491,7 +492,7 @@ responses = [{
     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation: "viewer",
     object: "document:roadmap",
-    contextualTuples: [{
+    contextual_tuples: [{
       user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
       relation: "writer",
       object: "document:roadmap"
@@ -537,7 +538,7 @@ const response = await fgaClient.listObjects({
   user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
   relation: "viewer",
   type: "document",
-  contextualTuples: [{
+  contextual_tuples: [{
     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation: "writer",
     object: "document:budget"
@@ -563,7 +564,7 @@ const response = await fgaClient.listRelations({
   user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
   object: "document:roadmap",
   relations: ["can_view", "can_edit", "can_delete"],
-  contextualTuples: [{
+  contextual_tuples: [{
     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation: "writer",
     object: "document:roadmap"
@@ -573,6 +574,49 @@ const response = await fgaClient.listRelations({
 // response.relations = ["can_view", "can_edit"]
 ```
 
+##### List Users
+
+List the users who have a certain relation to a particular type.
+
+[API Documentation](https://openfga.dev/api/service#/Relationship%20Queries/ListUsers)
+
+```js
+const options = {};
+
+// To override the authorization model id for this request
+options.authorization_model_id = "1uHxCSuTP0VKPYSnkq1pbb1jeZw";
+
+// Only a single filter is allowed for the time being
+const userFilters = [{type: "user"}];
+// user filters can also be of the form
+// const userFilters = [{type: "team", relation: "member"}];
+
+const response = await fgaClient.listUsers({
+  object: {
+    type: "document",
+    id: "roadmap"
+  },
+  relation: "can_read",
+  user_filters: userFilters,
+  context: {
+    "view_count": 100
+  },
+  contextualTuples:
+    [{
+      user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
+      relation: "editor",
+      object: "folder:product"
+    }, {
+      user: "folder:product",
+      relation: "parent",
+      object: "document:roadmap"
+    }]
+}, options);
+
+// response.users = [{object: {type: "user", id: "81684243-9356-4421-8fbf-a4f8d36aa31b"}}, {userset: { type: "user" }}, ...]
+// response.excluded_users = [ {object: {type: "user", id: "4a455e27-d15a-4434-82e0-136f9c2aa4cf"}}, ... ]
+```
+
 #### Assertions
 
 ##### Read Assertions
@@ -622,17 +666,19 @@ const response = await fgaClient.writeAssertions([{
 
 ### Retries
 
-By default API requests are retried up to 15 times on 429 and 5xx errors and credential requests are retried to 3 times on 429 and 5xx errors. In both instances they will wait a minimum of 100 milliseconds between requests and up to a maximum of 
+If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 15 times with a minimum wait time of 100 milliseconds between each attempt.
+
+To customize this behavior, create an object with `maxRetry` and `minWaitInMs` properties. `maxRetry` determines the maximum number of retries (up to 15), while `minWaitInMs` sets the minimum wait time between retries in milliseconds.
 
-In order to change the behavior for API requests, pass a `retryParams` object in the `OpenFgaClient` constructor with a `maxRetry` property to control the amount of retries and a `minWaitInMs` to control the minimum wait time between retried requests.
+Apply your custom retry values by setting to `retryParams` on the to the configuration object passed to the `OpenFgaClient` call.
 
 ```javascript
 const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';
 
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required
   storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
-  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID, // Optional, can be overridden per request
+  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
   retryParams: {
     maxRetry: 3, // retry up to 3 times on API requests
     minWaitInMs: 250 // wait a minimum of 250 milliseconds between requests