@api-client/core 0.14.1 → 0.14.3

package/src/modeling/types.ts

@@ -185,3 +185,548 @@ export type DataDomainGraph = Graph<unknown, DomainGraphNodeType, DomainGraphEdg
  * The serialized version of the data domain graph.
  */
 export type SerializedGraph = GraphJson<unknown, object, DomainGraphEdge>
+
+/**
+ * Represents a standardized, machine-readable error response body
+ * as defined by RFC 7807 for HTTP APIs.
+ */
+export interface ProblemDetails {
+  /**
+   * A URI that identifies the specific problem type. Should resolve to human-readable docs.
+   * e.g., "https://docs.apinow.app/errors/validation-failed"
+   */
+  type: string
+
+  /**
+   * A short, human-readable summary of the problem type.
+   * e.g., "Validation Error"
+   */
+  title: string
+
+  /**
+   * The HTTP status code generated by the origin server for this problem.
+   */
+  status?: number
+
+  /**
+   * A human-readable explanation specific to this occurrence of the problem.
+   */
+  detail?: string
+
+  /**
+   * A URI that identifies the specific occurrence of the problem.
+   * Can be the API request path that caused the error.
+   */
+  instance: string
+}
+
+/**
+ * The set of supported filter operators for the List action.
+ * These are used in query parameters, e.g., ?price[gte]=100
+ *
+ * - eq: Equal
+ * - nq: Not Equal
+ * - lt: Less Than
+ * - lte: Less Than or Equal
+ * - gt: Greater Than
+ * - gte: Greater Than or Equal
+ * - ex: Checks if the field exists
+ * - re: Regular expression match
+ * - bf: Date before a specific value
+ * - af: Date after a specific value
+ * - cn: String contains substring / Array contains element
+ * - st: String starts with
+ * - end: String ends with
+ * - in: Value is one of the elements in the provided array
+ * - nin: Value is not one of the elements in the provided array
+ */
+export type ResourceFilterOperator =
+  | 'eq' // Equal
+  | 'nq' // Not equal
+  | 'lt' // Less than
+  | 'lte' // Less than or equal
+  | 'gt' // Greater than
+  | 'gte' // Greater than or equal
+  | 'ex' // Checks if the field exists
+  | 're' // Regular expression match
+  | 'bf' // Date before a specific value
+  | 'af' // Date after a specific value
+  | 'cn' // String contains substring / Array contains element
+  | 'st' // String starts with
+  | 'end' // String ends with
+  | 'in' // Value is one of the elements in the provided array
+  | 'nin' // Value is not one of the elements in the provided array
+
+/**
+ * The session transport configuration interface.
+ * This defines the properties that are common to all session transports.
+ */
+interface SessionTransport {
+  /**
+   * Whether the session transport is enabled.
+   */
+  enabled: boolean
+  /**
+   * The kind of session transport. Each interface defines its own kind.
+   */
+  kind: string
+}
+
+/**
+ * Configuration for cookie-based session transport.
+ */
+export interface CookieConfiguration extends SessionTransport {
+  kind: 'cookie'
+  /**
+   * The lifetime of the cookie session.
+   * This is a string representing the duration, e.g., "7d" for 7 days or "24h" for 24 hours.
+   *
+   * @default "7d"
+   */
+  lifetime: string
+  /**
+   * Whether the cookie can only be accessed by the server.
+   * This is a security feature to prevent client-side scripts from accessing the cookie.
+   * If set to false, the cookie can be accessed by client-side scripts.
+   * @default true
+   */
+  httpOnly: boolean // Defaults to true
+  /**
+   * Whether the cookie should only be sent over secure connections (HTTPS).
+   * This is a security feature to prevent the cookie from being sent over unencrypted connections.
+   * @default true
+   */
+  secure: boolean
+  /**
+   * The SameSite attribute of the cookie.
+   * This attribute controls whether the cookie is sent with cross-site requests.
+   * - 'none' means the cookie is sent with cross-site requests.
+   * - 'lax' means the cookie is sent with top-level navigations and will be sent along with GET
+   *   requests initiated by third-party websites.
+   * @default 'none'
+   */
+  sameSite: 'none' | 'lax'
+  /**
+   * The name of the cookie.
+   * This is the key under which the session data will be stored in the cookie.
+   * @default 'as' - 'as' stands for "api session"
+   */
+  name: string
+}
+
+/**
+ * Configuration for JWT-based session transport.
+ */
+export interface JwtConfiguration extends SessionTransport {
+  kind: 'jwt'
+  /**
+   * The lifetime of the JWT token.
+   * This is a string representing the duration, e.g., "7d" for 7 days or "15m" for 15 minutes.
+   *
+   * @default "7d"
+   */
+  lifetime: string
+}
+
+export interface SessionConfiguration {
+  /**
+   * The secret used to sign the JWT and cookies. Should be handled securely.
+   * Not visible in the UI after being set.
+   */
+  secret: string
+  /**
+   * The properties from the `User` entity to be encoded into the session payload (JWT/cookie).
+   * These properties become available in the `request.auth` object at runtime.
+   */
+  properties: string[]
+  /**
+   * The cookie-based session transport configuration.
+   */
+  cookie?: CookieConfiguration
+
+  /**
+   * The JWT-based session transport configuration.
+   */
+  jwt?: JwtConfiguration
+}
+
+/**
+ * Defines the authorization strategy for the API.
+ * It is a base interface that can be extended for different strategies.
+ * For MVP, we will start with Roles-Based Access Control (RBAC).
+ */
+export interface AuthorizationConfiguration {
+  /**
+   * The authorization strategy. For MVP, we will start with RBAC.
+   * Post-MVP will include Permission-Based Access Control (PBAC).
+   * The strategy determines how users are granted access to resources.
+   *
+   * - RBAC (Roles-Based Access Control): Users are assigned roles, and permissions are granted to those roles.
+   * - PBAC (Permission-Based Access Control): Users are granted permissions directly, allowing for more
+   *   granular control.
+   */
+  strategy: string
+}
+
+export interface RolesBasedAccessControl extends AuthorizationConfiguration {
+  strategy: 'RBAC'
+  /**
+   * The property within the designated "User" entity that defines the user's role.
+   * This field is used in access rules to grant permissions.
+   *
+   * This property must be marked with the "Role" data semantic in the Data Modeler.
+   * It is required to publish the API.
+   */
+  roleKey: string
+}
+
+/**
+ * Configures the strategy for authenticating end-users.
+ * An API can only support one authentication strategy at a time.
+ * This is a base interface that can be extended for different strategies.
+ */
+export interface AuthenticationConfiguration {
+  /**
+   * The authentication method. For MVP, this is focused on username/password.
+   * This can be extended in the future to include 'SSO'.
+   */
+  strategy: string
+}
+
+/**
+ * Configuration for username/password authentication.
+ * This is the primary authentication method for the API (MVP).
+ */
+export interface UsernamePasswordConfiguration extends AuthenticationConfiguration {
+  strategy: 'UsernamePassword'
+  /**
+   * The specific property within the User entity that holds the password.
+   * This property must be marked with the "Password" data semantic in the Data Modeler.
+   *
+   * This property is required to publish the API.
+   */
+  passwordKey?: string
+}
+
+/**
+ * Represents a Data Entity from the Data Domain that the API will expose and operate upon.
+ */
+export interface ExposedEntity {
+  /**
+   * The key of the Data Entity from the Data Domain.
+   */
+  key: string
+
+  /**
+   * Optional configuration for resource-wide rate limiting and throttling.
+   * Defines rules to protect the resource from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+  /**
+   * Access control rules defining who can perform actions on this resource or collection.
+   * It override the top-level access rules defined in the API model.
+   */
+  accessRule?: AccessRule[]
+
+  /**
+   * The collection of API actions (e.g., List, Read, Create) enabled for this entity.
+   */
+  actions: ApiAction[]
+}
+
+/**
+ * Represents a specific, configurable API operation applied to a Data Entity.
+ * Corresponds to common RESTful interactions.
+ */
+export type ApiAction = ListAction | ReadAction | CreateAction | UpdateAction | DeleteAction | SearchAction
+
+/**
+ * A base interface for common properties across all actions.
+ */
+interface Action {
+  /**
+   * 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?: AccessRule[]
+  /**
+   * Optional configuration for action-wide rate limiting and throttling.
+   * Defines rules to protect the action from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+}
+
+/**
+ * Represents a pagination strategy for API actions that return collections of resources.
+ * This is a base interface that can be extended for different pagination strategies.
+ */
+export interface PaginationStrategy {
+  /**
+   * The kind of pagination strategy. This is used to identify the specific pagination method.
+   * For example, 'cursor' for cursor-based pagination or 'offset' for offset-based pagination.
+   */
+  kind: string
+  /**
+   * The default page size for the pagination strategy.
+   * This is the number of items returned per page when no specific page size is requested.
+   */
+  pageSize?: number
+}
+
+/**
+ * Represents the cursor-based pagination strategy.
+ */
+export interface CursorPaginationStrategy extends PaginationStrategy {
+  kind: 'cursor'
+}
+
+/**
+ * Represents the offset-based pagination strategy.
+ */
+export interface OffsetPaginationStrategy extends PaginationStrategy {
+  kind: 'offset'
+}
+
+/**
+ * Enables retrieving a collection of resources.
+ * Endpoint: GET /[entity-collection-name]
+ */
+export interface ListAction extends Action {
+  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 single resource by its ID.
+ * Endpoint: GET /[entity-collection-name]/{id}
+ */
+export interface ReadAction extends Action {
+  kind: 'read'
+  // Association handling (Link IDs vs. Embed) is defined on the
+  // data association itself in the Data Modeler.
+}
+
+/**
+ * Enables adding a new resource to a collection.
+ * Endpoint: POST /[entity-collection-name]
+ */
+export interface CreateAction extends Action {
+  kind: 'create'
+}
+
+/**
+ * Enables modifying an existing resource.
+ * Endpoints: PUT or PATCH /[entity-collection-name]/{id}
+ */
+export interface UpdateAction extends Action {
+  kind: 'update'
+  /**
+   * The allowed HTTP methods for updates. Default: PATCH only.
+   *
+   * These two methods represent the two common ways to update a resource:
+   * - PUT: Replaces the entire resource with the provided data.
+   * - PATCH: Applies a partial update to the resource, allowing for specific fields to be modified.
+   */
+  allowedMethods: ('PUT' | 'PATCH')[]
+}
+
+/**
+ * Enables removing an existing resource.
+ * Endpoint: DELETE /[entity-collection-name]/{id}
+ */
+export interface DeleteAction extends Action {
+  kind: 'delete'
+  /**
+   * The strategy for deletion. Default: Soft Delete.
+   *
+   * @default 'soft'
+   */
+  strategy?: 'soft' | 'hard'
+}
+
+/**
+ * Enables keyword-based search across specified fields.
+ * Endpoint: GET /[entity-collection-name]/search
+ */
+export interface SearchAction extends Action {
+  kind: 'search'
+  /**
+   * The fields within the entity to be included in the search scope.
+   * Must be "indexable" and typically text-based.
+   */
+  fields: string[]
+}
+
+/**
+ * Defines the access control policy for a specific API action.
+ * Based on the predefined rule types for session-based authentication.
+ */
+export type AccessRule =
+  | AllowPublicAccessRule
+  | AllowAuthenticatedAccessRule
+  | MatchResourceOwnerAccessRule
+  | MatchUserRoleAccessRule
+  | MatchUserPropertyAccessRule
+  | MatchEmailDomainAccessRule
+
+export interface BaseAccessRule {
+  /**
+   * The unique identifier for the access rule.
+   * This is used to reference the rule in the API configuration.
+   */
+  type: string
+}
+
+/**
+ * The action is allowed for all users, including unauthenticated ones.
+ * This is typically used for public APIs or resources that do not require authentication.
+ * It is the most permissive rule and should be used with caution.
+ */
+export interface AllowPublicAccessRule extends BaseAccessRule {
+  type: 'public'
+}
+/**
+ * The action is allowed for any authenticated user.
+ * This rule does not impose any additional restrictions based on user properties or resource ownership.
+ * It is used for resources that should be accessible to all logged-in users.
+ */
+export interface AllowAuthenticatedAccessRule extends BaseAccessRule {
+  type: 'authenticated'
+}
+/**
+ * The action is allowed if the authenticated user's ID matches a specific property on the resource.
+ * This is typically used to restrict access to resources owned by the user.
+ * For example, a user can only access their own profile or documents.
+ */
+export interface MatchResourceOwnerAccessRule extends BaseAccessRule {
+  type: 'resourceOwner'
+  /**
+   * The property on the resource that should match the authenticated user's ID.
+   * This is typically the ID of the user who owns the resource.
+   *
+   * The domain model should annotate this property with the "ResourceOwnerIdentifier" semantic
+   * to indicate that it is used for ownership checks.
+   */
+  property: string
+}
+
+/**
+ * The action is allowed if the authenticated user has a specific role.
+ * This is used to enforce role-based access control (RBAC).
+ * For example, only users with the "admin" role can perform certain actions.
+ */
+export interface MatchUserRoleAccessRule extends BaseAccessRule {
+  type: 'matchUserRole'
+  /**
+   * The role that the authenticated user must have to access the resource.
+   * This is typically a property on the user entity that defines their role.
+   *
+   * The domain model should annotate this property with the "UserRole" semantic
+   * to indicate that it is used for role-based access control.
+   */
+  role: string
+}
+/**
+ * The action is allowed if a specific property on the authenticated user matches an expected value.
+ * This is used to enforce other user-specific restrictions.
+ */
+export interface MatchUserPropertyAccessRule extends BaseAccessRule {
+  type: 'matchUserProperty'
+  /**
+   * The property on the authenticated user that should match the expected value.
+   */
+  property: string
+  /**
+   * The expected value for the user property.
+   */
+  value: string
+}
+/**
+ * The action is allowed if the authenticated user's email domain matches a specific domain.
+ * This is used to restrict access based on the user's email address.
+ * For example, only users with an email address from "mycompany.com" can access certain resources.
+ */
+export interface MatchEmailDomainAccessRule extends BaseAccessRule {
+  type: 'matchEmailDomain'
+  /**
+   * The email domain that the authenticated user's email must match.
+   */
+  domain: string
+}
+
+/**
+ * Defines the rate limiting and throttling policies for the entire API.
+ */
+export interface RateLimitingConfiguration {
+  /**
+   * An ordered list of rules. The first rule that matches an incoming
+   * request will be applied.
+   */
+  rules: RateLimitRule[]
+}
+
+/**
+ * Represents a single rate limiting rule that applies to a specific
+ * type of client, using a token bucket algorithm.
+ */
+export interface RateLimitRule {
+  /**
+   * A human-readable description of what this rule is for.
+   * e.g., "Limit anonymous users to 60 requests per hour."
+   */
+  description?: string
+
+  /**
+   * Defines how to group requests for rate limiting. This determines
+   * who the limit applies to.
+   *
+   * - 'ip': Keys on the client's IP address. Best for anonymous traffic.
+   * - 'userId': Keys on the authenticated user's ID. Best for logged-in users.
+   * - 'role': Applies a shared limit to all users of a specific role.
+   */
+  key: { type: 'ip' } | { type: 'userId' } | { type: 'role'; value: string }
+
+  /**
+   * The number of requests allowed over the defined interval.
+   * This is the rate at which tokens are added to the bucket.
+   */
+  rate: number
+
+  /**
+   * The time interval for the rate.
+   */
+  interval: 'second' | 'minute' | 'hour' | 'day'
+
+  /**
+   * The maximum number of requests that can be made in a burst.
+   * This represents the "bucket size." A larger burst allows for
+   * more requests to be made in a short period before throttling begins.
+   */
+  burst: number
+}

package/src/models/kinds.ts

@@ -20,3 +20,5 @@ export const DataCatalogKind = 'Core#DataCatalog'
 export const DataCatalogVersionKind = 'Core#DataCatalogVersion'
 export const OrganizationKind = 'Core#Organization'
 export const InvitationKind = 'Core#Invitation'
+export const ApiModelKind = 'Core#ApiModel'
+export const ApiFileKind = 'Core#ApiFile'

package/src/models/store/File.ts

@@ -181,6 +181,45 @@ export class StoredFile {
     this[shortcutTargetSymbol] = value
   }
 
+  /**
+   * Creates a file schema object with the given properties.
+   * The `key` is generated if not set.
+   *
+   * @param input The input to create the file schema.
+   * @returns The file schema object.
+   */
+  static createSchema(input: Partial<IStoredFile> = {}): IStoredFile {
+    const { key = nanoid(), kind, iconColor, shortcutTarget } = input
+    const result: IStoredFile = {
+      key,
+      kind: kind || '',
+      info: Thing.fromJSON(input.info, { name: 'Unnamed file' }).toJSON(),
+    }
+    if (iconColor) {
+      result.iconColor = iconColor
+    }
+    if (shortcutTarget) {
+      result.isShortcut = true
+      result.shortcutTarget = shortcutTarget
+    }
+    return result
+  }
+
+  constructor(state: IStoredFile) {
+    this.kind = state.kind
+    this.key = state.key
+    this.info = new Thing(state.info)
+    if (state.iconColor) {
+      this.iconColor = state.iconColor
+    }
+    if (state.shortcutTarget) {
+      this.shortcutTarget = state.shortcutTarget
+    }
+  }
+
+  /**
+   * @deprecated Use `createSchema()` and setup values in the constructor instead.
+   */
   new(init: IStoredFile): this {
     const { key = nanoid(), info, kind, iconColor, shortcutTarget } = init
     this.key = key
@@ -409,6 +448,64 @@ export class File extends StoredFile {
     return this[permissionsSymbol]
   }
 
+  static override createSchema(input: Partial<IFile> = {}): IFile {
+    const result = StoredFile.createSchema(input) as IFile
+    if (Array.isArray(input.parents)) {
+      result.parents = [...input.parents]
+    } else {
+      result.parents = []
+    }
+    if (Array.isArray(input.permissionIds)) {
+      result.permissionIds = [...input.permissionIds]
+    } else {
+      result.permissionIds = []
+    }
+    if (Array.isArray(input.permissions)) {
+      result.permissions = input.permissions.map((i) => ({ ...i }))
+    } else {
+      result.permissions = []
+    }
+    if (input.capabilities) {
+      result.capabilities = { ...input.capabilities }
+    }
+    if (input.lastModified) {
+      result.lastModified = { ...input.lastModified }
+    } else {
+      result.lastModified = { user: '', time: 0, byMe: false }
+    }
+    if (typeof input.deleted === 'boolean') {
+      result.deleted = input.deleted
+      result.deletedInfo = input.deletedInfo ? { ...input.deletedInfo } : undefined
+    }
+    if (Array.isArray(input.labels)) {
+      result.labels = [...input.labels]
+    }
+    if (typeof input.shortcutTarget === 'string') {
+      result.shortcutTarget = input.shortcutTarget
+    }
+    return result
+  }
+
+  constructor(state?: Partial<IFile>) {
+    const init = File.createSchema(state)
+    super(init)
+    this[parentsSymbol] = [...init.parents]
+    this[permissionIdsSymbol] = [...init.permissionIds]
+    this[permissionsSymbol] = init.permissions.map((i) => ({ ...i }))
+    this[capabilitiesSymbol] = init.capabilities ? { ...init.capabilities } : undefined
+    this[lastModifiedSymbol] = Object.freeze({ ...init.lastModified })
+    if (typeof init.deleted === 'boolean') {
+      this[deletedSymbol] = init.deleted
+      this[deletedInfoSymbol] = init.deletedInfo ? Object.freeze({ ...init.deletedInfo }) : undefined
+    }
+    if (Array.isArray(init.labels)) {
+      this.labels = [...init.labels]
+    }
+  }
+
+  /**
+   * @deprecated Use `createSchema()` and setup values in the constructor instead.
+   */
   override new(init: IFile): this {
     super.new(init)
     const { permissions = [], parents = [], permissionIds = [], deleted, deletedInfo, lastModified, labels } = init
@@ -453,20 +550,10 @@ export class File extends StoredFile {
 
   /**
    * @param name The name to set.
-   * @param owner The user id that is the owner of the file.
+   * @param kind The kind of the file to create.
    */
-  static fromName(name: string, kind = ''): File {
-    const key = nanoid()
-    const definition = new File()
-    definition.new({
-      key,
-      kind,
-      info: Thing.fromName(name).toJSON(),
-      parents: [],
-      permissionIds: [],
-      permissions: [],
-      lastModified: { user: '', time: 0, byMe: false },
-    })
+  static fromName(name: string, kind: string): File {
+    const definition = new File({ kind, info: { name } })
     return definition
   }