feat: add support for Write API idempotence with on_duplicate and on_missing options

CHANGELOG.md

@@ -5,7 +5,7 @@
 
 ## v0.9.0
 
-### [v0.9.0](https://github.com/openfga/js-sdk/compare/v0.8.1...v0.9.0) (2025-06-03)
+### [v0.9.0](https://github.com/openfga/js-sdk/compare/v0.8.1...v0.9.0) (2025-06-04)
 
 - feat: support client assertion for client credentials authentication (#228)
 

README.md

@@ -449,6 +449,8 @@ Similar to [check](#check), but instead of checking a single user-object relatio
 
 [API Documentation](https://openfga.dev/api/service#/Relationship%20Queries/BatchCheck)
 
+> **Note**: The order of `batchCheck` results is not guaranteed to match the order of the checks provided. Use `correlationId` to pair responses with requests.
+
 ```javascript
 const options = {
   // if you'd like to override the authorization model id for this request

apiModel.ts

@@ -1920,7 +1920,23 @@ export interface WriteRequestDeletes {
      * @memberof WriteRequestDeletes
      */
     tuple_keys: Array<TupleKeyWithoutCondition>;
+    /**
+     * On \'error\', the API returns an error when deleting a tuple that does not exist. On \'ignore\', deletes of non-existent tuples are treated as no-ops.
+     * @type {string}
+     * @memberof WriteRequestDeletes
+     */
+    on_missing?: WriteRequestDeletesOnMissingEnum;
 }
+
+/**
+    * @export
+    * @enum {string}
+    */
+export enum WriteRequestDeletesOnMissingEnum {
+    Error = 'error',
+    Ignore = 'ignore'
+}
+
 /**
  * 
  * @export
@@ -1933,5 +1949,21 @@ export interface WriteRequestWrites {
      * @memberof WriteRequestWrites
      */
     tuple_keys: Array<TupleKey>;
+    /**
+     * On \'error\' ( or unspecified ), the API returns an error if an identical tuple already exists. On \'ignore\', identical writes are treated as no-ops (matching on user, relation, object, and RelationshipCondition).
+     * @type {string}
+     * @memberof WriteRequestWrites
+     */
+    on_duplicate?: WriteRequestWritesOnDuplicateEnum;
 }
 
+/**
+    * @export
+    * @enum {string}
+    */
+export enum WriteRequestWritesOnDuplicateEnum {
+    Error = 'error',
+    Ignore = 'ignore'
+}
+
+

client.ts

@@ -16,6 +16,8 @@ import asyncPool = require("tiny-async-pool");
 
 import { OpenFgaApi } from "./api";
 import {
+  type WriteRequestDeletesOnMissingEnum,
+  type WriteRequestWritesOnDuplicateEnum,
   Assertion,
   BatchCheckItem,
   BatchCheckRequest,
@@ -127,7 +129,7 @@ export type ClientRequestOptsWithStoreId = ClientRequestOpts & StoreIdOpts;
 export type ClientRequestOptsWithAuthZModelId = ClientRequestOpts & StoreIdOpts & AuthorizationModelIdOpts;
 export type ClientRequestOptsWithConsistency = ClientRequestOpts & StoreIdOpts & AuthorizationModelIdOpts & ConsistencyOpts;
 
-export type PaginationOptions = { pageSize?: number, continuationToken?: string; };
+export type PaginationOptions = { pageSize?: number, continuationToken?: string, name?: string; };
 
 export type ClientCheckRequest = CheckRequestTupleKey &
     Pick<CheckRequest, "context"> &
@@ -187,12 +189,31 @@ export interface ClientBatchCheckResponse {
   result: ClientBatchCheckSingleResponse[];
 }
 
+export declare enum ClientWriteRequestWritesOnDuplicateEnum {
+    Error = "error",
+    Ignore = "ignore"
+}
+export declare enum ClientWriteRequestDeletesOnMissingEnum {
+    Error = "error",
+    Ignore = "ignore"
+}
+
 export interface ClientWriteRequestOpts {
   transaction?: {
     disable?: boolean;
     maxPerChunk?: number;
     maxParallelRequests?: number;
   }
+  idempotence?: {
+    /**
+     * On \'error\' ( or unspecified ), the API returns an error if an identical tuple already exists. On \'ignore\', identical writes are treated as no-ops (matching on user, relation, object, and RelationshipCondition).
+     */
+    on_duplicate?: ClientWriteRequestWritesOnDuplicateEnum;
+    /**
+     * On \'error\', the API returns an error when deleting a tuple that does not exist. On \'ignore\', deletes of non-existent tuples are treated as no-ops.
+     */
+    on_missing?: ClientWriteRequestDeletesOnMissingEnum;
+  }
 }
 
 export interface ClientWriteRequest {
@@ -311,14 +332,15 @@ export class OpenFgaClient extends BaseAPI {
    * @param {ClientRequestOpts & PaginationOptions} [options]
    * @param {number} [options.pageSize]
    * @param {string} [options.continuationToken]
+   * @param {string} [options.name] - Filter stores by name
    * @param {object} [options.headers] - Custom headers to send alongside the request
    * @param {object} [options.retryParams] - Override the retry parameters for this request
    * @param {number} [options.retryParams.maxRetry] - Override the max number of retries on each API request
    * @param {number} [options.retryParams.minWaitInMs] - Override the minimum wait before a retry is initiated
    * @throws { FgaError }
    */
   async listStores(options: ClientRequestOptsWithAuthZModelId & PaginationOptions = {}): PromiseResult<ListStoresResponse> {
-    return this.api.listStores(options.pageSize, options.continuationToken, options);
+    return this.api.listStores(options.pageSize, options.continuationToken, options.name, options);
   }
 
   /**
@@ -497,9 +519,15 @@ export class OpenFgaClient extends BaseAPI {
       };
       if (writes?.length) {
         apiBody.writes = { tuple_keys: writes };
+        if (options.idempotence?.on_duplicate) {
+          apiBody.writes.on_duplicate = options.idempotence.on_duplicate as unknown as WriteRequestWritesOnDuplicateEnum;
+        }
       }
       if (deletes?.length) {
         apiBody.deletes = { tuple_keys: deletes };
+        if (options.idempotence?.on_missing) {
+          apiBody.deletes.on_missing = options.idempotence.on_missing as unknown as WriteRequestDeletesOnMissingEnum;
+        }
       }
       await this.api.write(this.getStoreId(options)!, apiBody, options);
       return {

tests/client.test.ts

@@ -110,6 +110,26 @@ describe("OpenFGA Client", () => {
         expect(response.stores).toHaveLength(1);
         expect(response.stores?.[0]).toMatchObject(store);
       });
+
+      it("should properly call the ListStores API with name filter", async () => {
+        const store = { id: "some-id", name: "test-store" };
+        const scope = nocks.listStores(defaultConfiguration.getBasePath(), {
+          continuation_token: "",
+          stores: [{
+            ...store,
+            created_at: "2023-11-02T15:27:47.951Z",
+            updated_at: "2023-11-02T15:27:47.951Z",
+            deleted_at: "2023-11-02T15:27:47.951Z",
+          }],
+        }, 200, { name: "test-store" });
+
+        expect(scope.isDone()).toBe(false);
+        const response = await fgaClient.listStores({ name: "test-store" });
+
+        expect(scope.isDone()).toBe(true);
+        expect(response.stores).toHaveLength(1);
+        expect(response.stores?.[0]).toMatchObject(store);
+      });
     });
 
     describe("CreateStore", () => {

tests/helpers/nocks.ts

@@ -67,10 +67,13 @@ export const getNocks = ((nock: typeof Nock) => ({
       }]
     },
     responseCode = 200,
+    queryParams?: { page_size?: number; continuation_token?: string; name?: string },
   ) => {
-    return nock(basePath)
-      .get("/stores")
-      .reply(responseCode, response);
+    const mock = nock(basePath).get("/stores");
+    if (queryParams) {
+      mock.query(queryParams);
+    }
+    return mock.reply(responseCode, response);
   },
   createStore: (
     basePath = defaultConfiguration.getBasePath(),