@milaboratories/pl-client 2.18.4 → 3.0.0

package/dist/proto-rest/plapi.d.ts

@@ -4,6 +4,22 @@
  * Do not make direct changes to the file.
  */
 interface paths {
+  "/v1/auth/grant-access": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    post: operations["Platform_GrantAccess"];
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
   "/v1/auth/jwt-token": {
     parameters: {
       query?: never;
@@ -36,6 +52,22 @@ interface paths {
     patch?: never;
     trace?: never;
   };
+  "/v1/auth/revoke-grant": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    post: operations["Platform_RevokeGrant"];
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
   "/v1/controller/aliases-and-urls": {
     parameters: {
       query?: never;
@@ -228,7 +260,7 @@ interface paths {
     patch?: never;
     trace?: never;
   };
-  "/v1/locks/lease": {
+  "/v1/locks/lease/create": {
     parameters: {
       query?: never;
       header?: never;
@@ -236,9 +268,78 @@ interface paths {
       cookie?: never;
     };
     get?: never;
-    put: operations["Platform_UpdateLease"]; /** @description Locks */
+    put?: never;
+    /**
+     * @description LeaseResource creates a lease for a resource. A lease is a temporary lock that needs periodic renewal to stay valid.
+     *      Leases are a separate mechanism from locks: leases are focused on 'clients', while locks are focused on 'resources'.
+     *      To keep the lease active, the client needs the lease ID that is generated when a lease is created and used for lease updates.
+     */
     post: operations["Platform_LeaseResource"];
-    delete: operations["Platform_ReleaseLease"];
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/v1/locks/lease/release": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    post: operations["Platform_ReleaseLease"];
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/v1/locks/lease/update": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    post: operations["Platform_UpdateLease"];
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  "/v1/locks/lock/create": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    /**
+     * @description LockFieldValues gets the resource and obtains a lock on all resolved values of listed fields:
+     *        - get the resource that will take the lock ('FOR' resource) (lock cannot be obtained 'FOR' or 'ON' deleted resource)
+     *        - list resource's fields, take fields with names set in request
+     *        - get resolved values of listed fields (IDs of 'ON' resources).
+     *        - acquire lock on all 'ON' resources, marking 'FOR' resource as an owner.
+     *
+     *      Lock logic constraints:
+     *        - Locking is optimistic: if two processes try to obtain a lock on the same resource, one of them
+     *          succeeds, while the other fails with an error (no long waiting)
+     *        - Only resolved reference can be locked: to obtain a lock for a particular field's value, the backend needs to know
+     *          the resource ID this field points to. Unless all listed field references are resolved to a final ID, the lock will fail.
+     *        - Only an original resource can be locked: if a resource is 'pure' (supports deduplication), it has to pass deduplication before
+     *          being lockable. An attempt to lock a resource that has not become original will fail.
+     *        - Locking is a one-way operation: it cannot be 'released' or 'revoked'.
+     */
+    post: operations["Platform_LockFieldValues"];
+    delete?: never;
     options?: never;
     head?: never;
     patch?: never;
@@ -375,7 +476,8 @@ interface components {
     };
     DetachFilter_Response: Record<string, never>;
     Exists_Request: {
-      resourceId: string;
+      resourceId: string; /** Format: bytes */
+      resourceSignature: string;
     };
     Exists_Response: {
       exists: boolean;
@@ -385,27 +487,39 @@ interface components {
       type: number;
       features: components["schemas"]["Resource_Features"];
       /**
-       * @description _resolved_ value of field or _assigned_ if the field was assigned to a resource.
-       *      If field refers to another field, it will get
-       *      value only when this chain of references ends up with direct resource
-       *      reference. At that moment all fields in the chain will get their values
+       * @description _resolved_ value of a field or _assigned_ if the field was assigned to a resource.
+       *      If a field refers to another field, it will get
+       *      a value only when this chain of references ends up with a direct resource
+       *      reference. At that moment, all fields in the chain will get their values
        *      resolved and will start to refer to the same resource directly.
        */
       value: string;
+      /**
+       * Format: bytes
+       * @description Signature for value resource ID, inheriting the parent resource's color.
+       *      Populated server-side when the parent resource has a known color in the current TX.
+       */
+      valueSignature: string;
       /**
        * Format: enum
-       * @description If the value was empty, assigned or finally resolved.
+       * @description Whether the value is empty, assigned, or finally resolved.
        */
       valueStatus: number; /** @description If the value is in its final state (ready, duplicate or error) */
       valueIsFinal: boolean;
       /**
-       * @description Resource error resource id if any.
-       *      Is intended to report problems _from_ platform to client.
+       * @description Error resource ID, if any.
+       *      Is intended to report problems _from_ the platform to the client.
        */
       error: string;
+      /**
+       * Format: bytes
+       * @description Signature for error resource ID, inheriting the parent resource's color.
+       */
+      errorSignature: string;
     };
     FieldRef: {
-      resourceId: string;
+      resourceId: string; /** Format: bytes */
+      resourceSignature: string;
       fieldName: string;
     };
     FieldSchema: {
@@ -413,10 +527,12 @@ interface components {
       name: string;
     };
     GetJWTToken_Request: {
-      expiration: string;
+      expiration: string; /** Format: enum */
+      requestedRole: number;
     };
     GetJWTToken_Response: {
-      token: string;
+      token: string; /** Format: bytes */
+      sessionId: string;
     };
     GetNotifications_Request: {
       controllerType: string; /** Format: uint32 */
@@ -433,7 +549,8 @@ interface components {
       controllerUrl: string;
     };
     Get_Request: {
-      resourceId: string;
+      resourceId: string; /** Format: bytes */
+      resourceSignature: string;
       loadFields: boolean;
     };
     Get_Response: {
@@ -444,6 +561,16 @@ interface components {
     } & {
       [key: string]: unknown;
     };
+    GrantAccess_Request: {
+      resourceId: string; /** Format: bytes */
+      resourceSignature: string;
+      targetUser: string;
+      permissions: components["schemas"]["Grant_Permissions"];
+    };
+    GrantAccess_Response: Record<string, never>; /** @description Permissions describes access level for a grant. */
+    Grant_Permissions: {
+      writable: boolean;
+    };
     License_Response: {
       /** Format: int32 */status: number;
       isOk: boolean;
@@ -490,6 +617,7 @@ interface components {
       resourceCreated: boolean;
       resourceDeleted: boolean;
       resourceReady: boolean;
+      resourceRecovered: boolean;
       resourceDuplicate: boolean;
       resourceError: boolean; /** @description Field events */
       inputsLocked: boolean;
@@ -524,6 +652,7 @@ interface components {
       allOutputsSet: boolean;
       genericOtwSet: boolean;
       dynamicChanged: boolean;
+      resourceRecovered: boolean;
     };
     Notification_FieldChange: {
       old: components["schemas"]["Field"];
@@ -531,8 +660,7 @@ interface components {
     };
     Ping_Response: {
       coreVersion: string;
-      coreFullVersion: string;
-      serverInfo: string; /** Format: enum */
+      coreFullVersion: string; /** Format: enum */
       compression: number;
       /**
        * @description instanceID is a unique ID that changes when we reset DB state.
@@ -558,6 +686,7 @@ interface components {
     };
     Release_Request: {
       resourceId: string; /** Format: bytes */
+      resourceSignature: string; /** Format: bytes */
       leaseId: string;
     };
     Release_Response: Record<string, never>;
@@ -566,7 +695,8 @@ interface components {
     };
     RemoveAliasesAndUrls_Response: Record<string, never>;
     Resource: {
-      id: string; /** Format: bytes */
+      resourceId: string; /** Format: bytes */
+      resourceSignature: string; /** Format: bytes */
       canonicalId: string; /** Format: enum */
       kind: number;
       type: components["schemas"]["ResourceType"]; /** Format: bytes */
@@ -591,7 +721,31 @@ interface components {
     };
     ResourceSchema: {
       type: components["schemas"]["ResourceType"];
-      fields: components["schemas"]["FieldSchema"][];
+      fields: components["schemas"]["FieldSchema"][]; /** @description Access restriction flags for non-controller roles */
+      accessFlags: components["schemas"]["ResourceSchema_AccessFlags"];
+      freeInputs: boolean;
+      freeOutputs: boolean;
+    };
+    ResourceSchema_AccessFlags: {
+      /**
+       * @description Deny-list approach: default = allowed (true)
+       *      Controllers set these to false to restrict non-controller roles (role='u', role='w')
+       */
+      createResource: boolean; /** @description IMPORTANT: read_fields=false with write_fields=true is a forbidden combination */
+      readFields: boolean;
+      writeFields: boolean; /** @description IMPORTANT: read_kv=false with write_kv=true is a forbidden combination */
+      readKv: boolean;
+      writeKv: boolean;
+      /**
+       * @description Per-field-type overrides (map: field_type → bool)
+       *      When defined for a field type, overrides resource-level flags
+       */
+      readByFieldType: {
+        [key: string]: boolean;
+      };
+      writeByFieldType: {
+        [key: string]: boolean;
+      };
     };
     ResourceType: {
       name: string;
@@ -600,6 +754,12 @@ interface components {
     Resource_Features: {
       ephemeral: boolean;
     };
+    RevokeGrant_Request: {
+      resourceId: string; /** Format: bytes */
+      resourceSignature: string;
+      targetUser: string;
+    };
+    RevokeGrant_Response: Record<string, never>;
     SetFeatures_Request: {
       features: components["schemas"]["ResourceAPIFeature"][];
     };
@@ -646,6 +806,37 @@ interface components {
   pathItems: never;
 }
 interface operations {
+  Platform_GrantAccess: {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["GrantAccess_Request"];
+      };
+    };
+    responses: {
+      /** @description OK */200: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["GrantAccess_Response"];
+        };
+      }; /** @description Default error response */
+      default: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["Status"];
+        };
+      };
+    };
+  };
   Platform_GetJWTToken: {
     parameters: {
       query?: never;
@@ -704,6 +895,37 @@ interface operations {
       };
     };
   };
+  Platform_RevokeGrant: {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["RevokeGrant_Request"];
+      };
+    };
+    responses: {
+      /** @description OK */200: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["RevokeGrant_Response"];
+        };
+      }; /** @description Default error response */
+      default: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["Status"];
+        };
+      };
+    };
+  };
   Platform_WriteControllerAliasesAndUrls: {
     parameters: {
       query?: never;
@@ -1134,7 +1356,7 @@ interface operations {
       };
     };
   };
-  Platform_UpdateLease: {
+  Platform_LeaseResource: {
     parameters: {
       query?: never;
       header?: never;
@@ -1143,7 +1365,7 @@ interface operations {
     };
     requestBody: {
       content: {
-        "application/json": components["schemas"]["Update_Request"];
+        "application/json": components["schemas"]["Create_Request"];
       };
     };
     responses: {
@@ -1152,7 +1374,7 @@ interface operations {
           [name: string]: unknown;
         };
         content: {
-          "application/json": components["schemas"]["Update_Response"];
+          "application/json": components["schemas"]["Create_Response"];
         };
       }; /** @description Default error response */
       default: {
@@ -1165,7 +1387,7 @@ interface operations {
       };
     };
   };
-  Platform_LeaseResource: {
+  Platform_ReleaseLease: {
     parameters: {
       query?: never;
       header?: never;
@@ -1174,7 +1396,7 @@ interface operations {
     };
     requestBody: {
       content: {
-        "application/json": components["schemas"]["Create_Request"];
+        "application/json": components["schemas"]["Release_Request"];
       };
     };
     responses: {
@@ -1183,7 +1405,7 @@ interface operations {
           [name: string]: unknown;
         };
         content: {
-          "application/json": components["schemas"]["Create_Response"];
+          "application/json": components["schemas"]["Release_Response"];
         };
       }; /** @description Default error response */
       default: {
@@ -1196,7 +1418,7 @@ interface operations {
       };
     };
   };
-  Platform_ReleaseLease: {
+  Platform_UpdateLease: {
     parameters: {
       query?: never;
       header?: never;
@@ -1205,7 +1427,7 @@ interface operations {
     };
     requestBody: {
       content: {
-        "application/json": components["schemas"]["Release_Request"];
+        "application/json": components["schemas"]["Update_Request"];
       };
     };
     responses: {
@@ -1214,7 +1436,38 @@ interface operations {
           [name: string]: unknown;
         };
         content: {
-          "application/json": components["schemas"]["Release_Response"];
+          "application/json": components["schemas"]["Update_Response"];
+        };
+      }; /** @description Default error response */
+      default: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["Status"];
+        };
+      };
+    };
+  };
+  Platform_LockFieldValues: {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["Create_Request"];
+      };
+    };
+    responses: {
+      /** @description OK */200: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          "application/json": components["schemas"]["Create_Response"];
         };
       }; /** @description Default error response */
       default: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-client",
-  "version": "2.18.4",
+  "version": "3.0.0",
   "description": "New TS/JS client for Platform API",
   "files": [
     "./dist/**/*",
@@ -31,8 +31,8 @@
     "utility-types": "^3.11.0",
     "yaml": "^2.8.0",
     "@milaboratories/pl-http": "1.2.4",
-    "@milaboratories/pl-model-common": "1.31.0",
-    "@milaboratories/ts-helpers": "1.8.0"
+    "@milaboratories/ts-helpers": "1.8.1",
+    "@milaboratories/pl-model-common": "1.31.1"
   },
   "devDependencies": {
     "@protobuf-ts/plugin": "2.11.1",
@@ -41,8 +41,8 @@
     "openapi-typescript": "^7.10.0",
     "typescript": "~5.9.3",
     "vitest": "^4.0.18",
-    "@milaboratories/ts-builder": "1.3.0",
     "@milaboratories/build-configs": "1.5.2",
+    "@milaboratories/ts-builder": "1.3.0",
     "@milaboratories/ts-configs": "1.2.2"
   },
   "engines": {

package/src/core/ll_client.ts

@@ -25,6 +25,7 @@ import { defaultHttpDispatcher } from "@milaboratories/pl-http";
 import type { WireClientProvider, WireClientProviderFactory, WireConnection } from "./wire";
 import { parseHttpAuth } from "@milaboratories/pl-model-common";
 import type * as grpcTypes from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
+import { AuthAPI_GetJWTToken_Role } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
 import {
   type PlApiPaths,
   type PlRestClientType,
@@ -470,13 +471,19 @@ export class LLPlClient implements WireClientProviderFactory {
       const meta: Record<string, string> = {};
       if (options?.authorization) meta.authorization = options.authorization;
       return (
-        await cl.getJWTToken({ expiration: { seconds: ttlSeconds, nanos: 0 } }, { meta }).response
+        await cl.getJWTToken(
+          {
+            expiration: { seconds: ttlSeconds, nanos: 0 },
+            requestedRole: AuthAPI_GetJWTToken_Role.USER,
+          },
+          { meta },
+        ).response
       ).token;
     } else {
       const headers: Record<string, string> = {};
       if (options?.authorization) headers.authorization = options.authorization;
       const resp = cl.POST("/v1/auth/jwt-token", {
-        body: { expiration: `${ttlSeconds}s` },
+        body: { expiration: `${ttlSeconds}s`, requestedRole: AuthAPI_GetJWTToken_Role.USER },
         headers,
       });
       return notEmpty((await resp).data, "REST: empty response for JWT token request").token;

package/src/core/transaction.ts

@@ -518,12 +518,18 @@ export class PlTransaction {
   }
 
   public removeResource(rId: ResourceId): void {
-    this.sendVoidAsync({ oneofKind: "resourceRemove", resourceRemove: { id: rId } });
+    this.sendVoidAsync({
+      oneofKind: "resourceRemove",
+      resourceRemove: { resourceId: rId },
+    });
   }
 
   public resourceExists(rId: ResourceId): Promise<boolean> {
     return this.sendSingleAndParse(
-      { oneofKind: "resourceExists", resourceExists: { resourceId: rId } },
+      {
+        oneofKind: "resourceExists",
+        resourceExists: { resourceId: rId },
+      },
       (r) => r.resourceExists.exists,
     );
   }
@@ -581,7 +587,10 @@ export class PlTransaction {
       const result = await this.sendSingleAndParse(
         {
           oneofKind: "resourceGet",
-          resourceGet: { resourceId: toResourceId(rId), loadFields: loadFields },
+          resourceGet: {
+            resourceId: toResourceId(rId),
+            loadFields: loadFields,
+          },
         },
         (r) => protoToResource(notEmpty(r.resourceGet.resource)),
       );
@@ -689,7 +698,10 @@ export class PlTransaction {
   public setResourceError(rId: AnyResourceRef, ref: AnyResourceRef): void {
     this.sendVoidAsync({
       oneofKind: "resourceSetError",
-      resourceSetError: { resourceId: toResourceId(rId), errorResourceId: toResourceId(ref) },
+      resourceSetError: {
+        resourceId: toResourceId(rId),
+        errorResourceId: toResourceId(ref),
+      },
     });
   }
 
@@ -743,7 +755,10 @@ export class PlTransaction {
     this._stat.fieldsSet++;
     this.sendVoidAsync({
       oneofKind: "fieldSetError",
-      fieldSetError: { field: toFieldId(fId), errResourceId: toResourceId(ref) },
+      fieldSetError: {
+        field: toFieldId(fId),
+        errorResourceId: toResourceId(ref),
+      },
     });
   }
 
@@ -776,7 +791,11 @@ export class PlTransaction {
       const result = await this.sendMultiAndParse(
         {
           oneofKind: "resourceKeyValueList",
-          resourceKeyValueList: { resourceId: toResourceId(rId), startFrom: "", limit: 0 },
+          resourceKeyValueList: {
+            resourceId: toResourceId(rId),
+            startFrom: "",
+            limit: 0,
+          },
         },
         (r) => r.map((e) => e.resourceKeyValueList.record!),
       );
@@ -836,7 +855,10 @@ export class PlTransaction {
       const result = await this.sendSingleAndParse(
         {
           oneofKind: "resourceKeyValueGet",
-          resourceKeyValueGet: { resourceId: toResourceId(rId), key },
+          resourceKeyValueGet: {
+            resourceId: toResourceId(rId),
+            key,
+          },
         },
         (r) => r.resourceKeyValueGet.value,
       );
@@ -864,7 +886,10 @@ export class PlTransaction {
       const result = await this.sendSingleAndParse(
         {
           oneofKind: "resourceKeyValueGetIfExists",
-          resourceKeyValueGetIfExists: { resourceId: toResourceId(rId), key },
+          resourceKeyValueGetIfExists: {
+            resourceId: toResourceId(rId),
+            key,
+          },
         },
         (r) =>
           r.resourceKeyValueGetIfExists.exists ? r.resourceKeyValueGetIfExists.value : undefined,

package/src/core/type_conversion.ts

@@ -30,7 +30,7 @@ function resourceIsDeleted(proto: Resource): boolean {
 export function protoToResource(proto: Resource): ResourceData {
   if (resourceIsDeleted(proto)) throwPlNotFoundError("resource deleted");
   return {
-    id: proto.id as ResourceId,
+    id: proto.resourceId as ResourceId,
     originalResourceId: proto.originalResourceId as OptionalResourceId,
     type: notEmpty(proto.type),
     data: proto.data,