Add warnings to FGA query and check responses (#1280)

## Description
Adds warnings field to the FGA check and query responses. Warning types
include:

BaseWarning - catch all for warnings not supported by the current SDK
version
MissingContextKeysWarning - missing context keys found while evaluating
policies in the check / query request

Note: 

Query response returns "warnings" as a top-level field in the Paginate
response. To avoid affecting other packages, I extended the AutoPaginate
class in FGA package and added a custom deserializer.

Author: atainter

src/common/utils/pagination.ts

@@ -5,7 +5,7 @@ export class AutoPaginatable<T> {
   readonly options: PaginationOptions;
 
   constructor(
-    private list: List<T>,
+    protected list: List<T>,
     private apiCall: (params: PaginationOptions) => Promise<List<T>>,
     options?: PaginationOptions,
   ) {

src/fga/fga.spec.ts

@@ -44,6 +44,57 @@ describe('FGA', () => {
         warrantToken: 'abc',
       });
     });
+
+    it('deserializes warnings in check response', async () => {
+      fetchOnce({
+        result: 'authorized',
+        is_implicit: false,
+        warrant_token: 'abc',
+        warnings: [
+          {
+            code: 'missing_context_keys',
+            message: 'Missing required context keys',
+            keys: ['tenant_id', 'region'],
+          },
+          {
+            code: 'some_other_warning',
+            message: 'Some other warning message',
+          },
+        ],
+      });
+      const checkResult = await workos.fga.check({
+        checks: [
+          {
+            resource: {
+              resourceType: 'role',
+              resourceId: 'admin',
+            },
+            relation: 'member',
+            subject: {
+              resourceType: 'user',
+              resourceId: 'user_123',
+            },
+          },
+        ],
+      });
+      expect(fetchURL()).toContain('/fga/v1/check');
+      expect(checkResult).toMatchObject({
+        result: 'authorized',
+        isImplicit: false,
+        warrantToken: 'abc',
+        warnings: [
+          {
+            code: 'missing_context_keys',
+            message: 'Missing required context keys',
+            keys: ['tenant_id', 'region'],
+          },
+          {
+            code: 'some_other_warning',
+            message: 'Some other warning message',
+          },
+        ],
+      });
+    });
   });
 
   describe('createResource', () => {
@@ -618,6 +669,101 @@ describe('FGA', () => {
       ]);
     });
 
+    it('deserializes warnings in query response', async () => {
+      fetchOnce({
+        data: [
+          {
+            resource_type: 'role',
+            resource_id: 'admin',
+            warrant: {
+              resource_type: 'role',
+              resource_id: 'admin',
+              relation: 'member',
+              subject: {
+                resource_type: 'user',
+                resource_id: 'user_123',
+              },
+            },
+            is_implicit: false,
+          },
+          {
+            resource_type: 'role',
+            resource_id: 'manager',
+            warrant: {
+              resource_type: 'role',
+              resource_id: 'manager',
+              relation: 'member',
+              subject: {
+                resource_type: 'user',
+                resource_id: 'user_123',
+              },
+            },
+            is_implicit: true,
+          },
+        ],
+        list_metadata: {
+          before: null,
+          after: null,
+        },
+        warnings: [
+          {
+            code: 'missing_context_keys',
+            message: 'Missing required context keys',
+            keys: ['tenant_id'],
+          },
+          {
+            code: 'some_other_warning',
+            message: 'Some other warning message',
+          },
+        ],
+      });
+      const result = await workos.fga.query({
+        q: 'select role where user:user_123 is member',
+      });
+      expect(fetchURL()).toContain('/fga/v1/query');
+      expect(result.data).toMatchObject([
+        {
+          resourceType: 'role',
+          resourceId: 'admin',
+          warrant: {
+            resourceType: 'role',
+            resourceId: 'admin',
+            relation: 'member',
+            subject: {
+              resourceType: 'user',
+              resourceId: 'user_123',
+            },
+          },
+          isImplicit: false,
+        },
+        {
+          resourceType: 'role',
+          resourceId: 'manager',
+          warrant: {
+            resourceType: 'role',
+            resourceId: 'manager',
+            relation: 'member',
+            subject: {
+              resourceType: 'user',
+              resourceId: 'user_123',
+            },
+          },
+          isImplicit: true,
+        },
+      ]);
+      expect(result.warnings).toMatchObject([
+        {
+          code: 'missing_context_keys',
+          message: 'Missing required context keys',
+          keys: ['tenant_id'],
+        },
+        {
+          code: 'some_other_warning',
+          message: 'Some other warning message',
+        },
+      ]);
+    });
+
     it('sends correct params and options', async () => {
       fetchOnce({
         data: [

src/fga/fga.ts

@@ -29,10 +29,10 @@ import {
 } from './interfaces';
 import {
   deserializeBatchWriteResourcesResponse,
-  deserializeQueryResult,
   deserializeResource,
   deserializeWarrant,
   deserializeWarrantToken,
+  deserializeQueryResult,
   serializeBatchWriteResourcesOptions,
   serializeCheckBatchOptions,
   serializeCheckOptions,
@@ -45,6 +45,8 @@ import {
 import { isResourceInterface } from './utils/interface-check';
 import { AutoPaginatable } from '../common/utils/pagination';
 import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';
+import { FgaPaginatable } from './utils/fga-paginatable';
+import { fetchAndDeserializeFGAList } from './utils/fetch-and-deserialize-list';
 
 export class FGA {
   constructor(private readonly workos: WorkOS) {}
@@ -208,17 +210,17 @@ export class FGA {
   async query(
     options: QueryOptions,
     requestOptions: QueryRequestOptions = {},
-  ): Promise<AutoPaginatable<QueryResult>> {
-    return new AutoPaginatable(
-      await fetchAndDeserialize<QueryResultResponse, QueryResult>(
+  ): Promise<FgaPaginatable<QueryResult>> {
+    return new FgaPaginatable<QueryResult>(
+      await fetchAndDeserializeFGAList<QueryResultResponse, QueryResult>(
         this.workos,
         '/fga/v1/query',
         deserializeQueryResult,
         serializeQueryOptions(options),
         requestOptions,
       ),
       (params) =>
-        fetchAndDeserialize<QueryResultResponse, QueryResult>(
+        fetchAndDeserializeFGAList<QueryResultResponse, QueryResult>(
           this.workos,
           '/fga/v1/query',
           deserializeQueryResult,

src/fga/interfaces/check.interface.ts

@@ -3,6 +3,7 @@ import { PolicyContext, SerializedSubject, Subject } from './warrant.interface';
 import { CheckOp } from './check-op.enum';
 import { PostOptions } from '../../common/interfaces';
 import { deserializeDecisionTreeNode } from '../serializers/check-options.serializer';
+import { Warning } from './warning.interface';
 
 const CHECK_RESULT_AUTHORIZED = 'authorized';
 
@@ -49,6 +50,7 @@ export interface CheckResultResponse {
   is_implicit: boolean;
   warrant_token: string;
   debug_info?: DebugInfoResponse;
+  warnings?: Warning[];
 }
 
 export interface DebugInfo {
@@ -82,13 +84,15 @@ export interface CheckResultInterface {
   isImplicit: boolean;
   warrantToken: string;
   debugInfo?: DebugInfo;
+  warnings?: Warning[];
 }
 
 export class CheckResult implements CheckResultInterface {
   public result: string;
   public isImplicit: boolean;
   public warrantToken: string;
   public debugInfo?: DebugInfo;
+  public warnings?: Warning[];
 
   constructor(json: CheckResultResponse) {
     this.result = json.result;
@@ -102,6 +106,7 @@ export class CheckResult implements CheckResultInterface {
           ),
         }
       : undefined;
+    this.warnings = json.warnings;
   }
 
   isAuthorized(): boolean {

src/fga/interfaces/list.interface.ts

@@ -0,0 +1,10 @@
+import { List, ListResponse } from '../../common/interfaces';
+import { Warning } from './warning.interface';
+
+export interface FGAListResponse<T> extends ListResponse<T> {
+  warnings?: Warning[];
+}
+
+export interface FGAList<T> extends List<T> {
+  warnings?: Warning[];
+}

src/fga/interfaces/warning.interface.ts

@@ -0,0 +1,11 @@
+export interface BaseWarning {
+  code: string;
+  message: string;
+}
+
+export interface MissingContextKeysWarning extends BaseWarning {
+  code: 'missing_context_keys';
+  keys: string[];
+}
+
+export type Warning = BaseWarning | MissingContextKeysWarning;

src/fga/serializers/index.ts

@@ -10,3 +10,4 @@ export * from './resource.serializer';
 export * from './warrant-token.serializer';
 export * from './warrant.serializer';
 export * from './write-warrant-options.serializer';
+export * from './list.serializer';

src/fga/serializers/list.serializer.ts

@@ -0,0 +1,12 @@
+import { FGAList } from '../interfaces/list.interface';
+import { ListResponse } from '../../common/interfaces';
+
+export const deserializeFGAList = <T, U>(
+  response: ListResponse<T> & { warnings?: any[] },
+  deserializeFn: (data: T) => U,
+): FGAList<U> => ({
+  object: 'list',
+  data: response.data.map(deserializeFn),
+  listMetadata: response.list_metadata,
+  warnings: response.warnings,
+});

src/fga/serializers/query-result.serializer.ts

@@ -1,4 +1,11 @@
 import { QueryResult, QueryResultResponse } from '../interfaces';
+import { Warning } from '../interfaces/warning.interface';
+import { ListResponse } from '../../common/interfaces';
+
+export interface QueryResultListResponse
+  extends ListResponse<QueryResultResponse> {
+  warnings?: Warning[];
+}
 
 export const deserializeQueryResult = (
   queryResult: QueryResultResponse,

src/fga/utils/fetch-and-deserialize-list.ts

@@ -0,0 +1,23 @@
+import { WorkOS } from '../../workos';
+import { FGAList } from '../interfaces/list.interface';
+import { QueryRequestOptions } from '../interfaces';
+import { PaginationOptions } from '../../common/interfaces';
+import { ListResponse } from '../../common/interfaces';
+import { deserializeFGAList } from '../serializers/list.serializer';
+
+export const fetchAndDeserializeFGAList = async <T, U>(
+  workos: WorkOS,
+  endpoint: string,
+  deserializeFn: (data: T) => U,
+  options?: PaginationOptions,
+  requestOptions?: QueryRequestOptions,
+): Promise<FGAList<U>> => {
+  const { data: response } = await workos.get<
+    ListResponse<T> & { warnings?: any[] }
+  >(endpoint, {
+    query: options,
+    ...requestOptions,
+  });
+
+  return deserializeFGAList(response, deserializeFn);
+};

src/fga/utils/fga-paginatable.ts

@@ -0,0 +1,20 @@
+import { AutoPaginatable } from '../../common/utils/pagination';
+import { FGAList } from '../interfaces/list.interface';
+import { Warning } from '../interfaces/warning.interface';
+import { PaginationOptions } from '../../common/interfaces';
+
+export class FgaPaginatable<T> extends AutoPaginatable<T> {
+  protected override list!: FGAList<T>;
+
+  constructor(
+    list: FGAList<T>,
+    apiCall: (params: PaginationOptions) => Promise<FGAList<T>>,
+    options?: PaginationOptions,
+  ) {
+    super(list, apiCall, options);
+  }
+
+  get warnings(): Warning[] | undefined {
+    return this.list.warnings;
+  }
+}