@collective-intelligence/external-apps-server-sdk 0.0.0-stage → 0.1.1

package/dist/resources.d.ts

@@ -0,0 +1,423 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export type ResourceJsonValue = null | boolean | number | string | readonly ResourceJsonValue[] | Readonly<{
+	[key: string]: ResourceJsonValue;
+}>;
+/** Opaque wire identity. Callers must not infer or concatenate its internals. */
+export type ResourceId = string;
+export type ResourceRecordId = ResourceId;
+/** Opaque concurrency token independent from source timestamps. */
+export type ResourceRevision = string;
+/** Opaque pagination position issued and consumed only by a resource adapter. */
+export type ResourceCursor = string;
+export type IdempotencyKey = string;
+export type ResourceIdentityField = Readonly<{
+	name: string;
+	type: "number" | "string";
+}>;
+export type ResourceCapabilities = Readonly<{
+	create?: boolean;
+	/** Common entity deletion is always soft deletion. */
+	delete?: boolean;
+	get?: boolean;
+	hardDelete?: boolean;
+	includeDeleted?: boolean;
+	restore?: boolean;
+	search: true;
+	softDelete?: boolean;
+	update?: boolean;
+}>;
+export type ResourcePaginationMode = "cursor" | "page";
+export type PortableResourceSchema = Readonly<Record<string, ResourceJsonValue>>;
+export type ResourceDefinition<Entity, Create = Entity, Update = Partial<Entity>> = Readonly<{
+	capabilities: ResourceCapabilities;
+	concurrency: "revision";
+	id: string;
+	identity: Readonly<{
+		fields: readonly [
+			ResourceIdentityField,
+			...ResourceIdentityField[]
+		];
+	}>;
+	query: Readonly<{
+		filterableFields: readonly string[];
+		pagination: Readonly<{
+			modes: readonly ResourcePaginationMode[];
+		}>;
+		sortableFields: readonly string[];
+		textSearchFields?: readonly string[];
+	}>;
+	schemas: Readonly<{
+		create?: PortableResourceSchema;
+		entity: PortableResourceSchema;
+		update?: PortableResourceSchema;
+	}>;
+	version: string;
+	/** Portable UI metadata; required/enum/nullability remain in schemas. */
+	metadata?: Readonly<Record<string, ResourceJsonValue>>;
+	/** Type-only slots keep definition values portable and serializable. */
+	readonly __types?: Readonly<{
+		create: Create;
+		entity: Entity;
+		update: Update;
+	}>;
+}>;
+export type FilterValue = ResourceJsonValue | readonly ResourceJsonValue[];
+export type ResourceFilter = Readonly<{
+	field: string;
+	operator: "contains" | "ends_with" | "eq" | "gt" | "gte" | "in" | "lt" | "lte" | "ne" | "not_in" | "starts_with";
+	value: FilterValue;
+}> | Readonly<{
+	field: string;
+	operator: "is_not_null" | "is_null";
+}> | Readonly<{
+	filters: readonly ResourceFilter[];
+	operator: "and" | "or";
+}> | Readonly<{
+	filter: ResourceFilter;
+	operator: "not";
+}>;
+export type ResourceSort = Readonly<{
+	direction: "asc" | "desc";
+	field: string;
+}>;
+export type ResourcePagination = Readonly<{
+	mode: "cursor";
+	cursor?: ResourceCursor;
+	limit: number;
+}> | Readonly<{
+	mode: "page";
+	page: number;
+	pageSize: number;
+}>;
+export type ResourceListQuery = Readonly<{
+	filter?: ResourceFilter;
+	includeDeleted?: boolean;
+	pagination: ResourcePagination;
+	sort?: readonly ResourceSort[];
+	textSearch?: string;
+}>;
+export type ResourceRecord<Entity> = Readonly<{
+	deletedAt?: string;
+	id: ResourceRecordId;
+	revision: ResourceRevision;
+	value: Entity;
+}>;
+export type ResourceListResult<Entity> = Readonly<{
+	items: readonly ResourceRecord<Entity>[];
+	nextCursor?: ResourceCursor;
+	pagination: "cursor";
+}> | Readonly<{
+	items: readonly ResourceRecord<Entity>[];
+	page: number;
+	pageSize: number;
+	pagination: "page";
+	totalItems: number;
+	totalPages: number;
+}>;
+export type ResourceErrorCode = "capability_not_supported" | "conflict" | "forbidden" | "internal" | "invalid_request" | "not_found" | "rate_limited" | "transport_error" | "unauthenticated" | "unavailable";
+export type ResourceError = Readonly<{
+	code: ResourceErrorCode;
+	/** Client-observed dispatch outcome; uncertainty never proves rollback. */
+	outcome?: "not_dispatched" | "rejected" | "uncertain";
+	details?: Readonly<Record<string, ResourceJsonValue>>;
+	message: string;
+	retryable: boolean;
+}>;
+export type ResourceResult<Value> = Readonly<{
+	correlationId: string;
+	ok: true;
+	value: Value;
+}> | Readonly<{
+	correlationId: string;
+	error: ResourceError;
+	ok: false;
+}>;
+export type ResourceListRequest = Readonly<{
+	operation: "list";
+	query: ResourceListQuery;
+	requestId: string;
+	resourceId: string;
+}>;
+export type ResourceGetRequest = Readonly<{
+	id: ResourceRecordId;
+	includeDeleted?: boolean;
+	operation: "get";
+	requestId: string;
+	resourceId: string;
+}>;
+export type ResourceCreateRequest<Create> = Readonly<{
+	idempotencyKey: IdempotencyKey;
+	operation: "create";
+	requestId: string;
+	resourceId: string;
+	value: Create;
+}>;
+export type ResourceUpdateRequest<Update> = Readonly<{
+	expectedRevision: ResourceRevision;
+	id: ResourceRecordId;
+	idempotencyKey?: IdempotencyKey;
+	operation: "update";
+	requestId: string;
+	resourceId: string;
+	value: Update;
+}>;
+export type ResourceLifecycleRequest = Readonly<{
+	expectedRevision: ResourceRevision;
+	id: ResourceRecordId;
+	idempotencyKey?: IdempotencyKey;
+	operation: "hard_delete" | "restore" | "soft_delete";
+	requestId: string;
+	resourceId: string;
+}>;
+export type ResourceTransportRequest = ResourceCreateRequest<unknown> | ResourceGetRequest | ResourceLifecycleRequest | ResourceListRequest | ResourceUpdateRequest<unknown>;
+export type ResourceMutationInput<Value> = Readonly<{
+	expectedRevision: ResourceRevision;
+	id: ResourceRecordId;
+	idempotencyKey?: IdempotencyKey;
+	value: Value;
+}>;
+export type ResourceLifecycleInput = Readonly<{
+	expectedRevision: ResourceRevision;
+	id: ResourceRecordId;
+	idempotencyKey?: IdempotencyKey;
+}>;
+export type ResourceCreateInput<Value> = Readonly<{
+	idempotencyKey: IdempotencyKey;
+	value: Value;
+}>;
+/** Common entity operations. Generic resource lifecycle/cursor APIs remain separate. */
+export type EntityOperation = "list" | "get" | "create" | "update" | "delete";
+export type EntityListQuery = Omit<ResourceListQuery, "pagination" | "includeDeleted"> & Readonly<{
+	pagination: Extract<ResourcePagination, {
+		mode: "page";
+	}>;
+}>;
+export type EntityPage<Value> = Extract<ResourceListResult<Value>, {
+	pagination: "page";
+}>;
+export type EntityCreateInput<Value> = ResourceCreateInput<Value>;
+export type EntityUpdateInput<Patch> = ResourceMutationInput<Patch> & Readonly<{
+	idempotencyKey: IdempotencyKey;
+}>;
+export type EntityDeleteInput = ResourceLifecycleInput & Readonly<{
+	idempotencyKey: IdempotencyKey;
+}>;
+export type EntityRequestIdentity = Readonly<{
+	requestId: string;
+	resourceId: string;
+}>;
+export type EntityRequest<Create = unknown, Patch = unknown> = EntityRequestIdentity & (Readonly<{
+	operation: "list";
+	query: EntityListQuery;
+}> | Readonly<{
+	operation: "get";
+	id: ResourceRecordId;
+}> | (Readonly<{
+	operation: "create";
+}> & EntityCreateInput<Create>) | (Readonly<{
+	operation: "update";
+}> & EntityUpdateInput<Patch>) | (Readonly<{
+	operation: "delete";
+}> & EntityDeleteInput));
+/** Application login identities are separate from gateway machine callers. */
+export type ApplicationUserIdentity = Readonly<{
+	kind: "local_user";
+	id: string;
+	email: string;
+	name: string | null;
+} | {
+	kind: "ci_user";
+	id: string;
+	email: string | null;
+	name: string | null;
+	issuer: string;
+	organizationId: string;
+}>;
+/** Constructed only after user/app/organization authorization at server ingress.
+ * Canonical identities survive proxy hops and scope mutation receipts; credentials
+ * and request/correlation IDs are deliberately not part of that logical identity.
+ */
+export type EntityInvocationContext = Readonly<{
+	applicationId: string;
+	issuer: string;
+	organizationId: string;
+	resourceId: string;
+	roles: readonly string[];
+	scopes: readonly string[];
+	teamIds: readonly string[];
+	user: ApplicationUserIdentity;
+}>;
+export type PrincipalKind = "detached_user" | "service_principal";
+export type DelegatedSubjectPolicy = "allowed" | "forbidden" | "required";
+export type AuthorizationRequirement = Readonly<{
+	delegatedSubject?: DelegatedSubjectPolicy;
+	organization: "required";
+	principalKinds: readonly PrincipalKind[];
+	scopes: readonly string[];
+}>;
+export type ExternalAuditSubject = Readonly<{
+	issuer: string;
+	mappedCiUserId?: string;
+	subject: string;
+}>;
+export type GatewayCallerIdentity = Readonly<{
+	audience: readonly string[];
+	binding: string;
+	expiresAt: number;
+	installationId: string;
+	issuer: string;
+	organizationId: string;
+	principalKind: PrincipalKind;
+	requestId: string;
+	scopes: readonly string[];
+	subject: string;
+}>;
+export type GatewayInvocationContext = Readonly<{
+	caller: GatewayCallerIdentity;
+	correlationId: string;
+	externalAuditSubject?: ExternalAuditSubject;
+	organizationId: string;
+}>;
+/** Common CRUD port. Implementations own atomic revisions, receipts and soft deletion. */
+export interface EntityRepository<Value, Create = Value, Patch = Partial<Value>> {
+	readonly list: (query: EntityListQuery, context: EntityInvocationContext) => Promise<EntityPage<Value>>;
+	readonly get?: (id: string, context: EntityInvocationContext) => Promise<ResourceRecord<Value>>;
+	readonly create?: (input: EntityCreateInput<Create>, context: EntityInvocationContext) => Promise<ResourceRecord<Value>>;
+	readonly update?: (input: EntityUpdateInput<Patch>, context: EntityInvocationContext) => Promise<ResourceRecord<Value>>;
+	readonly delete?: (input: EntityDeleteInput, context: EntityInvocationContext) => Promise<ResourceRecord<Value>>;
+}
+export type ResourceChange<Entity> = Readonly<{
+	kind: "upsert";
+	record: ResourceRecord<Entity>;
+}> | Readonly<{
+	kind: "tombstone";
+	id: string;
+	revision: string;
+	deletedAt: string;
+}>;
+export type ResourceChangePage<Entity> = Readonly<{
+	changes: readonly ResourceChange<Entity>[];
+	nextCursor?: string;
+}>;
+/** Full inventory only: no filters, text search or caller-selected ordering.
+ * Continue consecutive pages with the first watermark. A conflict requires restart.
+ */
+export type ResourceInventoryRequest = Readonly<{
+	page: number;
+	pageSize: number;
+	watermark?: string;
+}>;
+export type ResourceInventoryPage<Entity> = Extract<ResourceListResult<Entity>, {
+	pagination: "page";
+}> & Readonly<{
+	/** Resource-scoped committed change cursor; consume deltas strictly after it. */
+	watermark: string;
+}>;
+export type ResourceMutation = Readonly<{
+	id: string;
+	expectedRevision: string;
+}>;
+export interface CrudRepository<Entity, Create = Entity, Update = Partial<Entity>> {
+	readonly list: (query: ResourceListQuery, context?: EntityInvocationContext) => Promise<ResourceListResult<Entity>>;
+	readonly scan?: (request: ResourceInventoryRequest) => Promise<ResourceInventoryPage<Entity>>;
+	readonly get?: (id: string, includeDeleted?: boolean, context?: EntityInvocationContext) => Promise<ResourceRecord<Entity>>;
+	readonly create?: (value: Create, idempotencyKey: string, context?: EntityInvocationContext) => Promise<ResourceRecord<Entity>>;
+	readonly update?: (input: ResourceMutation & Readonly<{
+		value: Update;
+	}>, context?: EntityInvocationContext) => Promise<ResourceRecord<Entity>>;
+	readonly hardDelete?: (input: ResourceMutation, context?: EntityInvocationContext) => Promise<void>;
+	readonly softDelete?: (input: ResourceMutation, context?: EntityInvocationContext) => Promise<ResourceRecord<Entity>>;
+	readonly restore?: (input: ResourceMutation, context?: EntityInvocationContext) => Promise<ResourceRecord<Entity>>;
+	readonly changes?: (input: Readonly<{
+		cursor?: string;
+		limit: number;
+	}>) => Promise<ResourceChangePage<Entity>>;
+}
+declare const repositoryErrorBrand: unique symbol;
+declare class ResourceRepositoryError extends Error {
+	readonly [repositoryErrorBrand] = true;
+	readonly code: ResourceErrorCode;
+	readonly retryable: boolean;
+	readonly details: ResourceError["details"];
+	constructor(code: ResourceErrorCode, message: string, retryable?: boolean, details?: ResourceError["details"]);
+}
+/** A configured local or CI-backed binding; no storage policy is exposed to browsers. */
+export type EntityResourceDefinition<Value = unknown, Create = Value, Patch = Partial<Value>> = Readonly<{
+	definition: ResourceDefinition<Value, Create, Patch>;
+	execute: (request: EntityRequest<Create, Patch>, context: EntityInvocationContext, options?: Readonly<{
+		signal?: AbortSignal;
+	}>) => Promise<ResourceResult<EntityPage<Value> | ResourceRecord<Value>>>;
+}>;
+export type GatewayResourceOperation = ResourceTransportRequest["operation"];
+export type GatewayResourceAuthorization = Readonly<Partial<Record<GatewayResourceOperation, AuthorizationRequirement>>>;
+export type GatewayResourceDefinition<Entity = unknown, Create = Entity, Update = Partial<Entity>> = Readonly<{
+	authorization: GatewayResourceAuthorization;
+	definition: ResourceDefinition<Entity, Create, Update>;
+	execute: (request: ResourceTransportRequest, context: GatewayInvocationContext, options?: Readonly<{
+		signal?: AbortSignal;
+	}>) => Promise<ResourceResult<unknown>>;
+	scan?: (request: ResourceInventoryRequest & Readonly<{
+		requestId: string;
+		resourceId: string;
+	}>, context: GatewayInvocationContext, options?: Readonly<{
+		signal?: AbortSignal;
+	}>) => Promise<ResourceResult<unknown>>;
+	changes?: (request: Readonly<{
+		cursor?: string;
+		limit: number;
+		requestId: string;
+		resourceId: string;
+	}>, context: GatewayInvocationContext, options?: Readonly<{
+		signal?: AbortSignal;
+	}>) => Promise<ResourceResult<unknown>>;
+}>;
+export type CrudResource<Entity = unknown, Create = Entity, Update = Partial<Entity>> = GatewayResourceDefinition<Entity, Create, Update> & Readonly<{
+	executeCrud: (request: ResourceTransportRequest, context: EntityInvocationContext) => Promise<ResourceResult<unknown>>;
+}>;
+export type ResourceHttpHandlerOptions<Value = unknown, Create = Value, Patch = Partial<Value>> = Readonly<{
+	resource: CrudResource<Value, Create, Patch> | EntityResourceDefinition<Value, Create, Patch>;
+	/** Mount path including the entity name, e.g. /api/leads. */
+	basePath: string;
+	/** Host verifies the current CI session and resource policy; no browser identity is trusted. */
+	authorize: (request: Request, operation: ResourceTransportRequest["operation"] | EntityOperation) => Promise<EntityInvocationContext | Response>;
+	maxBodyBytes?: number;
+}>;
+export type EntityHttpRoute = {
+	readonly kind: "search";
+} | {
+	readonly kind: "collection";
+} | {
+	readonly kind: "record";
+	readonly id: string;
+} | {
+	readonly kind: "soft_delete";
+	readonly id: string;
+};
+export declare const createResourceHttpHandler: <Value, Create = Value, Patch = Partial<Value>>(options: ResourceHttpHandlerOptions<Value, Create, Patch>) => (request: Request) => Promise<Response>;
+export declare const matchEntityHttpRoute: (pathname: string, basePath: string) => EntityHttpRoute | null;
+export declare const defineCrudResource: <Entity, Create = Entity, Update = Partial<Entity>>(input: Readonly<{
+	definition: ResourceDefinition<Entity, Create, Update>;
+	repository: CrudRepository<Entity, Create, Update>;
+	authorization: GatewayResourceAuthorization;
+}>) => CrudResource<Entity, Create, Update>;
+export declare const defineEntityResource: <Value, Create = Value, Patch = Partial<Value>>(input: Readonly<{
+	definition: ResourceDefinition<Value, Create, Patch>;
+	repository: EntityRepository<Value, Create, Patch>;
+}>) => EntityResourceDefinition<Value, Create, Patch>;
+export declare const defineCiEntityResource: <Value, Create = Value, Patch = Partial<Value>>(input: Readonly<{
+	definition: ResourceDefinition<Value, Create, Patch>;
+	tenantUrl: string;
+	schemaFqn: string;
+	organizationId: string;
+	fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}>) => EntityResourceDefinition<Value, Create, Patch>;
+export declare const defineGatewayResource: <Entity, Create = Entity, Update = Partial<Entity>>(resource: GatewayResourceDefinition<Entity, Create, Update>) => GatewayResourceDefinition<Entity, Create, Update>;
+declare const ResourceRepositoryError$1: typeof ResourceRepositoryError;
+type ResourceRepositoryError$1 = ResourceRepositoryError;
+
+export {
+	ResourceRepositoryError$1 as ResourceRepositoryError,
+};
+
+export {};