@api-client/core 0.18.57 → 0.18.58

package/data/models/example-generator-api.json

@@ -42062,12 +42062,15 @@
 "@id": "#209"
 },
 {
-"@id": "#194"
+"@id": "#206"
 },
 {
 "@id": "#191"
 },
 {
+"@id": "#194"
+},
+{
 "@id": "#197"
 },
 {
@@ -42077,9 +42080,6 @@
 "@id": "#203"
 },
 {
-"@id": "#206"
-},
-{
 "@id": "#209"
 }
 ],
@@ -42810,16 +42810,16 @@
 "@id": "#219"
 },
 {
-"@id": "#210"
+"@id": "#219"
 },
 {
-"@id": "#213"
+"@id": "#216"
 },
 {
-"@id": "#216"
+"@id": "#210"
 },
 {
-"@id": "#219"
+"@id": "#213"
 }
 ],
 "doc:root": false,
@@ -43457,7 +43457,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
+"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43478,7 +43478,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43499,7 +43499,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43520,7 +43520,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
+"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43541,7 +43541,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
+"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44232,7 +44232,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
+"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44253,7 +44253,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
+"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44274,7 +44274,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44295,7 +44295,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44761,27 +44761,27 @@
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#199",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#205/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#205",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#208/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#208",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#223/source-map/lexical/element_0",
@@ -45116,22 +45116,22 @@
 {
 "@id": "#212/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#212",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#215/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#215",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#218/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#218",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#221/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#221",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#338/source-map/synthesized-field/element_1",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.18.57",
+  "version": "0.18.58",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/ApiModel.ts

@@ -2,12 +2,10 @@ import { nanoid } from '../nanoid.js'
 import { ApiModelKind, DataDomainKind, ExposedEntityKind } from '../models/kinds.js'
 import { type IThing, Thing } from '../models/Thing.js'
 import type {
-  AccessRule,
   AssociationTarget,
   AuthenticationConfiguration,
   AuthorizationConfiguration,
   ExposedEntitySchema,
-  RateLimitingConfiguration,
   RolesBasedAccessControl,
   SessionConfiguration,
   UsernamePasswordConfiguration,
@@ -19,6 +17,8 @@ import { observed, toRaw } from '../decorators/observed.js'
 import pluralize from '@jarrodek/pluralize'
 import { createDomainKey } from './helpers/keying.js'
 import { ExposedEntity } from './ExposedEntity.js'
+import { AccessRule, AccessRuleSchema } from './rules/AccessRule.js'
+import { RateLimitingConfiguration, RateLimitingConfigurationSchema } from './rules/RateLimitingConfiguration.js'
 
 /**
  * Contact information for the exposed API.
@@ -106,12 +106,12 @@ export interface ApiModelSchema extends DependentModelSchema {
    * These rules apply to all exposed entities and actions. An API action
    * can declare its own access rules, which will override these.
    */
-  accessRule?: AccessRule[]
+  accessRule?: AccessRuleSchema[]
   /**
    * Optional configuration for API-wide rate limiting and throttling.
    * Defines rules to protect the API from overuse.
    */
-  rateLimiting?: RateLimitingConfiguration
+  rateLimiting?: RateLimitingConfigurationSchema
   /**
    * A URL to the Terms of Service for the API.
    */
@@ -179,12 +179,12 @@ export class ApiModel extends DependentModel {
    * These rules apply to all exposed entities and actions. An API action
    * can declare its own access rules, which will override these.
    */
-  accessRule?: AccessRule[]
+  @observed({ deep: true }) accessor accessRule: AccessRule[]
   /**
    * Optional configuration for API-wide rate limiting and throttling.
    * Defines rules to protect the API from overuse.
    */
-  rateLimiting?: RateLimitingConfiguration
+  @observed() accessor rateLimiting: RateLimitingConfiguration | undefined
   /**
    * A URL to the Terms of Service for the API.
    */
@@ -238,25 +238,25 @@ export class ApiModel extends DependentModel {
       exposes,
     }
     if (input.user) {
-      result.user = { ...input.user }
+      result.user = structuredClone(input.user)
     }
     if (input.dependencyList) {
       result.dependencyList = structuredClone(input.dependencyList)
     }
     if (input.authentication) {
-      result.authentication = input.authentication
+      result.authentication = structuredClone(input.authentication)
     }
     if (input.authorization) {
-      result.authorization = input.authorization
+      result.authorization = structuredClone(input.authorization)
     }
     if (input.session) {
-      result.session = input.session
+      result.session = structuredClone(input.session)
     }
-    if (input.accessRule) {
-      result.accessRule = input.accessRule
+    if (Array.isArray(input.accessRule)) {
+      result.accessRule = structuredClone(input.accessRule)
     }
     if (input.rateLimiting) {
-      result.rateLimiting = input.rateLimiting
+      result.rateLimiting = structuredClone(input.rateLimiting)
     }
     if (input.termsOfService) {
       result.termsOfService = input.termsOfService
@@ -309,11 +309,13 @@ export class ApiModel extends DependentModel {
     } else {
       this.exposes = []
     }
-    if (init.accessRule) {
-      this.accessRule = structuredClone(init.accessRule)
+    if (Array.isArray(init.accessRule)) {
+      this.accessRule = init.accessRule.map((rule) => new AccessRule(rule))
+    } else {
+      this.accessRule = []
     }
     if (init.rateLimiting) {
-      this.rateLimiting = structuredClone(init.rateLimiting)
+      this.rateLimiting = new RateLimitingConfiguration(init.rateLimiting)
     }
     if (init.termsOfService) {
       this.termsOfService = init.termsOfService
@@ -352,11 +354,11 @@ export class ApiModel extends DependentModel {
     if (this.session) {
       result.session = structuredClone(this.session)
     }
-    if (this.accessRule) {
-      result.accessRule = structuredClone(this.accessRule)
+    if (Array.isArray(this.accessRule) && this.accessRule.length > 0) {
+      result.accessRule = this.accessRule.map((rule) => rule.toJSON())
     }
     if (this.rateLimiting) {
-      result.rateLimiting = structuredClone(this.rateLimiting)
+      result.rateLimiting = this.rateLimiting.toJSON()
     }
     if (this.termsOfService) {
       result.termsOfService = this.termsOfService

package/src/modeling/ExposedEntity.ts

@@ -1,17 +1,12 @@
 import { observed } from '../decorators/observed.js'
 import { ExposedEntityKind } from '../models/kinds.js'
 import { nanoid } from '../nanoid.js'
+import { Action } from './actions/Action.js'
 import type { ApiModel } from './ApiModel.js'
 import { ensureLeadingSlash, joinPaths } from './helpers/endpointHelpers.js'
-import type {
-  AccessRule,
-  ApiAction,
-  AssociationTarget,
-  ExposeOptions,
-  ExposeParentRef,
-  RateLimitingConfiguration,
-  ExposedEntitySchema,
-} from './types.js'
+import { AccessRule } from './rules/AccessRule.js'
+import { RateLimitingConfiguration } from './rules/RateLimitingConfiguration.js'
+import type { AssociationTarget, ExposeOptions, ExposeParentRef, ExposedEntitySchema } from './types.js'
 
 /**
  * A class that specializes in representing an exposed Data Entity within an API Model.
@@ -91,7 +86,7 @@ export class ExposedEntity extends EventTarget {
   /**
    * The list of enabled API actions for this exposure (List/Read/Create/etc.)
    */
-  @observed({ deep: true }) accessor actions: ApiAction[]
+  @observed({ deep: true }) accessor actions: Action[]
 
   /**
    * Optional array of access rules that define the access control policies for this exposure.
@@ -162,7 +157,7 @@ export class ExposedEntity extends EventTarget {
     if (exposeOptions !== undefined) {
       result.exposeOptions = { ...exposeOptions }
     }
-    if (accessRule !== undefined) {
+    if (Array.isArray(accessRule)) {
       result.accessRule = accessRule.map((ar) => ({ ...ar }))
     }
     if (rateLimiting !== undefined) {
@@ -187,9 +182,9 @@ export class ExposedEntity extends EventTarget {
     this.isRoot = init.isRoot
     this.parent = init.parent
     this.exposeOptions = init.exposeOptions
-    this.actions = init.actions
-    this.accessRule = init.accessRule
-    this.rateLimiting = init.rateLimiting
+    this.actions = init.actions ? init.actions.map((a) => new Action(a)) : []
+    this.accessRule = init.accessRule ? init.accessRule.map((ar) => new AccessRule(ar)) : []
+    this.rateLimiting = init.rateLimiting ? new RateLimitingConfiguration(init.rateLimiting) : undefined
     this.truncated = init.truncated
     this.#initializing = false
   }
@@ -212,7 +207,7 @@ export class ExposedEntity extends EventTarget {
       key: this.key,
       entity: { ...this.entity },
       resourcePath: this.resourcePath,
-      actions: this.actions.map((a) => ({ ...a })),
+      actions: this.actions.map((a) => a.toJSON()),
       hasCollection: this.hasCollection,
     }
     if (this.collectionPath !== undefined) {
@@ -227,11 +222,11 @@ export class ExposedEntity extends EventTarget {
     if (this.exposeOptions !== undefined) {
       result.exposeOptions = { ...this.exposeOptions }
     }
-    if (this.accessRule !== undefined) {
-      result.accessRule = this.accessRule.map((ar) => ({ ...ar }))
+    if (Array.isArray(this.accessRule) && this.accessRule.length > 0) {
+      result.accessRule = this.accessRule.map((ar) => ar.toJSON())
     }
     if (this.rateLimiting !== undefined) {
-      result.rateLimiting = { ...this.rateLimiting }
+      result.rateLimiting = this.rateLimiting.toJSON()
     }
     if (this.truncated !== undefined) {
       result.truncated = this.truncated

package/src/modeling/actions/Action.ts

@@ -0,0 +1,64 @@
+import { AccessRule, AccessRuleSchema } from '../rules/AccessRule.js'
+import { RateLimitingConfiguration, RateLimitingConfigurationSchema } from '../rules/RateLimitingConfiguration.js'
+import { observed } from '../../decorators/observed.js'
+
+/**
+ * A base interface for common properties across all actions.
+ */
+export interface ActionSchema {
+  /**
+   * The specific kind of action (e.g., 'List', 'Read', etc.)
+   */
+  kind: string
+  /**
+   * Access control rules defining who can perform this action. It is only applied if the
+   * authorization strategy is set to 'RBAC'.
+   * If no rules grant access, it's denied by default making it essentially private.
+   *
+   * Note, the API can defined top level access rules that apply to all actions. If this property is set,
+   * it overrides the top level access rules for this specific action.
+   *
+   * It is an ordered list, meaning the first rule that matches the user will be applied.
+   * If multiple rules match, the first one in the list takes precedence.
+   * If no rules match, the action is denied.
+   */
+  accessRule?: AccessRuleSchema[]
+  /**
+   * Optional configuration for action-wide rate limiting and throttling.
+   * Defines rules to protect the action from overuse.
+   */
+  rateLimiting?: RateLimitingConfigurationSchema
+}
+
+/**
+ * A base class for common properties across all actions.
+ */
+export class Action extends EventTarget implements ActionSchema {
+  @observed() accessor kind: string
+  @observed({ deep: true }) accessor accessRule: AccessRule[]
+  @observed({ deep: true }) accessor rateLimiting: RateLimitingConfiguration | undefined
+
+  constructor(state: Partial<ActionSchema> = {}) {
+    super()
+    this.kind = state.kind || ''
+    this.accessRule = state.accessRule ? state.accessRule.map((rule) => new AccessRule(rule)) : []
+    this.rateLimiting = state.rateLimiting ? new RateLimitingConfiguration(state.rateLimiting) : undefined
+  }
+
+  notifyChange() {
+    this.dispatchEvent(new Event('change'))
+  }
+
+  toJSON(): ActionSchema {
+    const result: ActionSchema = {
+      kind: this.kind,
+    }
+    if (this.accessRule.length) {
+      result.accessRule = this.accessRule.map((rule) => rule.toJSON())
+    }
+    if (this.rateLimiting) {
+      result.rateLimiting = this.rateLimiting.toJSON()
+    }
+    return result
+  }
+}

package/src/modeling/actions/CreateAction.ts

@@ -0,0 +1,30 @@
+import { Action, type ActionSchema } from './Action.js'
+import { observed } from '../../decorators/observed.js'
+
+/**
+ * Enables adding a new resource to a collection.
+ * Endpoint: POST /[entity-collection-name]
+ */
+export interface CreateActionSchema extends ActionSchema {
+  kind: 'create'
+}
+
+/**
+ * Enables adding a new resource to a collection.
+ * Endpoint: POST /[entity-collection-name]
+ */
+export class CreateAction extends Action implements CreateActionSchema {
+  @observed() override accessor kind: 'create'
+
+  constructor(state: Partial<CreateActionSchema> = {}) {
+    super(state)
+    this.kind = 'create'
+  }
+
+  override toJSON(): CreateActionSchema {
+    return {
+      ...(super.toJSON() as CreateActionSchema),
+      kind: 'create',
+    }
+  }
+}

package/src/modeling/actions/DeleteAction.ts

@@ -0,0 +1,51 @@
+import { Action, type ActionSchema } from './Action.js'
+import { observed } from '../../decorators/observed.js'
+
+export type DeleteStrategy = 'soft' | 'hard'
+
+/**
+ * Enables removing an existing resource.
+ * Endpoint: DELETE /[entity-collection-name]/{id}
+ */
+export interface DeleteActionSchema extends ActionSchema {
+  kind: 'delete'
+  /**
+   * The strategy for deletion. Default: Soft Delete.
+   *
+   * @default 'soft'
+   */
+  strategy?: DeleteStrategy
+  /**
+   * The data retention period (in days) for soft-deleted resources.
+   * This defines how long the data should be kept before it is permanently deleted.
+   *
+   * @default 30
+   */
+  retentionPeriod?: number
+}
+
+/**
+ * Enables removing an existing resource.
+ * Endpoint: DELETE /[entity-collection-name]/{id}
+ */
+export class DeleteAction extends Action implements DeleteActionSchema {
+  @observed() override accessor kind: 'delete'
+  @observed() accessor strategy: DeleteStrategy
+  @observed() accessor retentionPeriod: number
+
+  constructor(state: Partial<DeleteActionSchema> = {}) {
+    super(state)
+    this.kind = 'delete'
+    this.strategy = state.strategy || 'soft'
+    this.retentionPeriod = state.retentionPeriod ?? 30
+  }
+
+  override toJSON(): DeleteActionSchema {
+    return {
+      ...(super.toJSON() as DeleteActionSchema),
+      kind: 'delete',
+      strategy: this.strategy,
+      retentionPeriod: this.retentionPeriod,
+    }
+  }
+}

package/src/modeling/actions/ListAction.ts

@@ -0,0 +1,58 @@
+import type { PaginationStrategy } from '../types.js'
+import { Action, type ActionSchema } from './Action.js'
+import { observed, toRaw } from '../../decorators/observed.js'
+
+/**
+ * Enables retrieving a collection of resources.
+ * Endpoint: GET /[entity-collection-name]
+ */
+export interface ListActionSchema extends ActionSchema {
+  kind: 'list'
+  /**
+   * The pagination strategy used for this action.
+   * This defines how the results are paginated when retrieving a collection of resources.
+   * It can be either 'cursor' or 'offset'.
+   */
+  pagination: PaginationStrategy
+  /**
+   * Fields from the entity that can be used for filtering.
+   * Must be marked as "indexable" in the Data Model.
+   */
+  filterableFields: string[]
+  /**
+   * Fields from the entity that can be used for sorting.
+   */
+  sortableFields: string[]
+}
+
+/**
+ * Enables retrieving a collection of resources.
+ * Endpoint: GET /[entity-collection-name]
+ */
+export class ListAction extends Action implements ListActionSchema {
+  @observed() override accessor kind: 'list'
+  @observed({ deep: true }) accessor pagination: PaginationStrategy
+  @observed({ deep: true }) accessor filterableFields: string[]
+  @observed({ deep: true }) accessor sortableFields: string[]
+
+  constructor(state: Partial<ListActionSchema> = {}) {
+    super(state)
+    this.kind = state.kind || 'list'
+    this.pagination = state.pagination
+      ? { ...state.pagination }
+      : {
+          kind: 'offset',
+        }
+    this.filterableFields = state.filterableFields ? [...state.filterableFields] : []
+    this.sortableFields = state.sortableFields ? [...state.sortableFields] : []
+  }
+
+  override toJSON(): ListActionSchema {
+    return {
+      ...(super.toJSON() as ListActionSchema),
+      pagination: structuredClone(toRaw(this, this.pagination)) as PaginationStrategy,
+      filterableFields: structuredClone(toRaw(this, this.filterableFields)) as string[],
+      sortableFields: structuredClone(toRaw(this, this.sortableFields)) as string[],
+    }
+  }
+}

package/src/modeling/actions/ReadAction.ts

@@ -0,0 +1,32 @@
+import { Action, type ActionSchema } from './Action.js'
+import { observed } from '../../decorators/observed.js'
+
+/**
+ * Enables retrieving a single resource by its ID.
+ * Endpoint: GET /[entity-collection-name]/{id}
+ */
+export interface ReadActionSchema extends ActionSchema {
+  kind: 'read'
+  // Association handling (Link IDs vs. Embed) is defined on the
+  // data association itself in the Data Modeler.
+}
+
+/**
+ * Enables retrieving a single resource by its ID.
+ * Endpoint: GET /[entity-collection-name]/{id}
+ */
+export class ReadAction extends Action implements ReadActionSchema {
+  @observed() override accessor kind: 'read'
+
+  constructor(state: Partial<ReadActionSchema> = {}) {
+    super(state)
+    this.kind = 'read'
+  }
+
+  override toJSON(): ReadActionSchema {
+    return {
+      ...(super.toJSON() as ReadActionSchema),
+      kind: 'read',
+    }
+  }
+}

package/src/modeling/actions/SearchAction.ts

@@ -0,0 +1,38 @@
+import { Action, type ActionSchema } from './Action.js'
+import { observed, toRaw } from '../../decorators/observed.js'
+
+/**
+ * Enables keyword-based search across specified fields.
+ * Endpoint: GET /[entity-collection-name]/search
+ */
+export interface SearchActionSchema extends ActionSchema {
+  kind: 'search'
+  /**
+   * The fields within the entity to be included in the search scope.
+   * Must be "indexable" and typically text-based.
+   */
+  fields: string[]
+}
+
+/**
+ * Enables keyword-based search across specified fields.
+ * Endpoint: GET /[entity-collection-name]/search
+ */
+export class SearchAction extends Action implements SearchActionSchema {
+  @observed() override accessor kind: 'search'
+  @observed({ deep: true }) accessor fields: string[]
+
+  constructor(state: Partial<SearchActionSchema> = {}) {
+    super(state)
+    this.kind = 'search'
+    this.fields = state.fields ? [...state.fields] : []
+  }
+
+  override toJSON(): SearchActionSchema {
+    return {
+      ...(super.toJSON() as SearchActionSchema),
+      kind: 'search',
+      fields: structuredClone(toRaw(this, this.fields)) as string[],
+    }
+  }
+}