@api-client/core 0.14.2 → 0.14.3

package/src/modeling/Semantics.ts

@@ -10,14 +10,44 @@ export enum SemanticType {
   /**
    * Designates a Data Entity that represents users of the system.
    */
-  User = 'https://apinow.app/semantics/entities/#User',
+  User = 'Semantic#User',
 
   // Property-Level Semantics
-  CreatedTimestamp = 'https://apinow.app/semantics/properties/#CreatedTimestamp',
-  UpdatedTimestamp = 'https://apinow.app/semantics/properties/#UpdatedTimestamp',
-  DeletedTimestamp = 'https://apinow.app/semantics/properties/#DeletedTimestamp',
-  DeletedFlag = 'https://apinow.app/semantics/properties/#DeletedFlag',
-  PublicUniqueName = 'https://apinow.app/semantics/properties/#PublicUniqueName',
+  /**
+   * Annotates the field as the user password.
+   * The runtime should treat this field with special care,
+   * ensuring it is encrypted and not exposed in API responses.
+   */
+  Password = 'Semantic#Password',
+  /**
+   * Designates a Data Property as the `createdAt` timestamp of an entity.
+   * This is used to track when the entity was first created.
+   */
+  CreatedTimestamp = 'Semantic#CreatedTimestamp',
+  /**
+   * Designates a Data Property as the `updatedAt` timestamp of an entity.
+   * This is used to track when the entity was last modified.
+   */
+  UpdatedTimestamp = 'Semantic#UpdatedTimestamp',
+  /**
+   * Designates a Data Property as the `deletedAt` timestamp of an entity.
+   * This is used to track when the entity was soft-deleted.
+   * Soft-deletion means the entity is not physically removed from the database,
+   * but marked as deleted for logical deletion purposes.
+   */
+  DeletedTimestamp = 'Semantic#DeletedTimestamp',
+  /**
+   * Designates a Data Property as a boolean flag indicating whether the entity is deleted.
+   * This is used for soft-deletion, where the entity is not physically removed from the database,
+   * but marked as deleted.
+   */
+  DeletedFlag = 'Semantic#DeletedFlag',
+  /**
+   * Designates a Data Property as a unique public identifier for a resource.
+   * This is often used in URLs to provide a user-friendly way to access the resource.
+   * For example, a blog post might have a public unique name like "my-first-post".
+   */
+  PublicUniqueName = 'Semantic#PublicUniqueName',
   /**
    * Designates a Data Property as the `role` of a user within the system.
    * This is used to define the user's permissions and access levels.
@@ -25,17 +55,34 @@ export enum SemanticType {
    * compared to a user with the role of "guest".
    * Roles are defined on the entity as enums, or as a string property with a controlled vocabulary.
    */
-  UserRole = 'https://apinow.app/semantics/entities/#UserRole',
+  UserRole = 'Semantic#UserRole',
   // Association-Level Semantics
-  ResourceOwnerIdentifier = 'https://apinow.app/semantics/associations/#ResourceOwnerIdentifier',
+  /**
+   * Designates an association that links a resource to a "User" entity instance.
+   * This is used to indicate ownership of the resource for access control purposes.
+   * For example, a blog post might have a resource owner identifier that points to the user who created it.
+   */
+  ResourceOwnerIdentifier = 'Semantic#ResourceOwnerIdentifier',
 }
 
 /**
  * Defines the scope at which a semantic can be applied.
  */
 export enum SemanticScope {
+  /**
+   * The semantic applies to an entire Data Entity.
+   * This is used for semantics that provide context or constraints at the entity level.
+   */
   Entity = 'Entity',
+  /**
+   * The semantic applies to a single Data Property.
+   * This is used for semantics that provide context or constraints at the property level.
+   */
   Property = 'Property',
+  /**
+   * The semantic applies to an Association between Data Entities.
+   * This is used for semantics that provide context or constraints at the association level.
+   */
   Association = 'Association',
 }
 
@@ -127,6 +174,14 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
   },
 
   // Property-Level Definitions
+  [SemanticType.Password]: {
+    id: SemanticType.Password,
+    displayName: 'User Password',
+    scope: SemanticScope.Property,
+    description:
+      'Annotates the field as the user password. The runtime should treat this field with special care, ensuring it is encrypted and not exposed in API responses.',
+    applicableDataTypes: ['string'],
+  },
   [SemanticType.CreatedTimestamp]: {
     id: SemanticType.CreatedTimestamp,
     displayName: 'Creation Timestamp',

package/src/modeling/amf/ShapeGenerator.ts

@@ -107,7 +107,7 @@ export class ShapeGenerator {
    * const amfShape = generator.entity(myDomainEntity);
    * ```
    */
-  entity(input: DomainEntity, visited: Set<string> = new Set<string>()): IApiNodeShape | IApiRecursiveShape {
+  entity(input: DomainEntity, visited = new Set<string>()): IApiNodeShape | IApiRecursiveShape {
     if (visited.has(input.key)) {
       // create a recursive shape.
       return this.createRecursiveShape(input)

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'