js-bao-wss-client / ResourceMetadataAPI
Interface: ResourceMetadataAPI
Sub-API for reading and writing typed resource metadata (values only — category definitions are managed by app admins, not through this client). Reads are gated per category by its readRule and writes by its writeRule, with an app-level owner/admin bypass; a resource-level permission never bypasses. A denial surfaces as an HTTP 403 error on the single read/write calls (get/set/list/delete) and as a per-item ok: false entry in the batch. resolve is the exception: a denial there is reported as a miss, not a 403 — see its doc below.
Methods
delete()
delete(
resourceType,resourceId,category):Promise<ResourceMetadataDeleteResult>
Delete one resource's metadata for one category. The category's writeRule gates the delete (403 on denial). Idempotent: deleting an item that does not exist succeeds with deleted: false rather than failing with 404.
Parameters
resourceType
string
resourceId
string
category
string
Returns
Promise<ResourceMetadataDeleteResult>
get()
get<
T>(resourceType,resourceId,category):Promise<ResourceMetadataReadResult<T>>
Read one resource's metadata for one category. Succeeds with exists: false and empty data when nothing has been written yet; fails with 404 when the category is not defined for the resource type, or 403 when the category's readRule denies the caller.
Type Parameters
T
T extends object = Record<string, unknown>
Parameters
resourceType
string
resourceId
string
category
string
Returns
Promise<ResourceMetadataReadResult<T>>
getBatch()
getBatch(
params):Promise<ResourceMetadataBatchResult>
Read metadata for many resources in one call (bounded: 50 resources / 200 resource-category pairs). Partial success: per-item 403/404 errors are returned as structured entries and do not fail the call.
Parameters
params
Returns
Promise<ResourceMetadataBatchResult>
list()
list(
resourceType,resourceId):Promise<ResourceMetadataListResult>
List every stored metadata category on one resource. Only categories the caller may read are returned (each gated by its readRule, with the app-level owner/admin bypass); a resource with no metadata comes back with an empty categories array.
Parameters
resourceType
string
resourceId
string
Returns
Promise<ResourceMetadataListResult>
resolve()
resolve(
params):Promise<ResourceMetadataResolveResult>
Look a resource up by the value of a category's unique field — the reverse of a metadata read. Useful for mapping an external identifier (a payment provider's customer ID, an SSO subject, an imported record key) back onto the resource that owns it.
A value no readable resource owns comes back as { resourceId: null } — a miss is a success, not an error. The category's readRule is applied to the resolved resource, and a denied read returns that same miss shape, so the response body never reveals whether a value you may not read exists. Only the body is indistinguishable: a denied resolve does the rule evaluation a miss skips, so it is not constant-time. Fails with 400 NOT_UNIQUE_FIELD when key is not the category's active unique field, and 404 when the category is not defined for the resource type.
Parameters
params
Returns
Promise<ResourceMetadataResolveResult>
set()
set<
T>(resourceType,resourceId,category,data):Promise<ResourceMetadataWriteResult<T>>
Write (full replace) one resource's metadata for one category. The data is validated against the category's schema; the category's writeRule gates the write (403 on denial).
Type Parameters
T
T extends object = Record<string, unknown>
Parameters
resourceType
string
resourceId
string
category
string
data
T
Returns
Promise<ResourceMetadataWriteResult<T>>