@objectstack/spec 0.1.2 → 0.2.0

package/dist/data/filter.zod.d.ts

@@ -0,0 +1,295 @@
+import { z } from 'zod';
+/**
+ * Unified Query DSL Specification
+ *
+ * Based on industry best practices from:
+ * - Prisma ORM
+ * - Strapi CMS
+ * - TypeORM
+ * - LoopBack Framework
+ *
+ * Version: 1.0.0
+ * Status: Draft
+ *
+ * Objective: Define a JSON-based, database-agnostic query syntax standard
+ * for data filtering interactions between frontend and backend APIs.
+ *
+ * Design Principles:
+ * 1. Declarative: Frontend describes "what data to get", not "how to query"
+ * 2. Database Agnostic: Syntax contains no database-specific directives
+ * 3. Type Safe: Structure can be statically inferred by TypeScript
+ * 4. Convention over Configuration: Implicit syntax for common queries
+ */
+/**
+ * Comparison operators for equality and inequality checks.
+ * Supported data types: Any
+ */
+export declare const EqualityOperatorSchema: z.ZodObject<{
+    /** Equal to (default) - SQL: = | MongoDB: $eq */
+    $eq: z.ZodOptional<z.ZodAny>;
+    /** Not equal to - SQL: <> or != | MongoDB: $ne */
+    $ne: z.ZodOptional<z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    $eq?: any;
+    $ne?: any;
+}, {
+    $eq?: any;
+    $ne?: any;
+}>;
+/**
+ * Comparison operators for numeric and date comparisons.
+ * Supported data types: Number, Date
+ */
+export declare const ComparisonOperatorSchema: z.ZodObject<{
+    /** Greater than - SQL: > | MongoDB: $gt */
+    $gt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    /** Greater than or equal to - SQL: >= | MongoDB: $gte */
+    $gte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    /** Less than - SQL: < | MongoDB: $lt */
+    $lt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    /** Less than or equal to - SQL: <= | MongoDB: $lte */
+    $lte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+}, "strip", z.ZodTypeAny, {
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+}, {
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+}>;
+/**
+ * Set operators for membership checks.
+ */
+export declare const SetOperatorSchema: z.ZodObject<{
+    /** In list - SQL: IN (?, ?, ?) | MongoDB: $in */
+    $in: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    /** Not in list - SQL: NOT IN (...) | MongoDB: $nin */
+    $nin: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+}, "strip", z.ZodTypeAny, {
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+}, {
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+}>;
+/**
+ * Range operator for interval checks (closed interval).
+ * SQL: BETWEEN ? AND ? | MongoDB: $gte AND $lte
+ */
+export declare const RangeOperatorSchema: z.ZodObject<{
+    /** Between (inclusive) - takes [min, max] array */
+    $between: z.ZodOptional<z.ZodTuple<[z.ZodUnion<[z.ZodNumber, z.ZodDate]>, z.ZodUnion<[z.ZodNumber, z.ZodDate]>], null>>;
+}, "strip", z.ZodTypeAny, {
+    $between?: [number | Date, number | Date] | undefined;
+}, {
+    $between?: [number | Date, number | Date] | undefined;
+}>;
+/**
+ * String pattern matching operators.
+ * Note: Case sensitivity should be handled at backend level.
+ */
+export declare const StringOperatorSchema: z.ZodObject<{
+    /** Contains substring - SQL: LIKE %?% | MongoDB: $regex */
+    $contains: z.ZodOptional<z.ZodString>;
+    /** Starts with prefix - SQL: LIKE ?% | MongoDB: $regex */
+    $startsWith: z.ZodOptional<z.ZodString>;
+    /** Ends with suffix - SQL: LIKE %? | MongoDB: $regex */
+    $endsWith: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+}, {
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+}>;
+/**
+ * Special check operators for null and existence.
+ */
+export declare const SpecialOperatorSchema: z.ZodObject<{
+    /** Is null check - SQL: IS NULL (true) / IS NOT NULL (false) | MongoDB: field: null */
+    $null: z.ZodOptional<z.ZodBoolean>;
+    /** Field exists check (primarily for NoSQL) - MongoDB: $exists */
+    $exist: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}, {
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}>;
+/**
+ * All field-level operators combined.
+ * These can be applied to individual fields in a filter.
+ */
+export declare const FieldOperatorsSchema: z.ZodObject<{
+    $eq: z.ZodOptional<z.ZodAny>;
+    $ne: z.ZodOptional<z.ZodAny>;
+    $gt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $gte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $lt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $lte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $in: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    $nin: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    $between: z.ZodOptional<z.ZodTuple<[z.ZodUnion<[z.ZodNumber, z.ZodDate]>, z.ZodUnion<[z.ZodNumber, z.ZodDate]>], null>>;
+    $contains: z.ZodOptional<z.ZodString>;
+    $startsWith: z.ZodOptional<z.ZodString>;
+    $endsWith: z.ZodOptional<z.ZodString>;
+    $null: z.ZodOptional<z.ZodBoolean>;
+    $exist: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    $eq?: any;
+    $ne?: any;
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+    $between?: [number | Date, number | Date] | undefined;
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}, {
+    $eq?: any;
+    $ne?: any;
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+    $between?: [number | Date, number | Date] | undefined;
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}>;
+/**
+ * Recursive filter type that supports:
+ * 1. Implicit equality: { field: value }
+ * 2. Explicit operators: { field: { $op: value } }
+ * 3. Logical combinations: { $and: [...], $or: [...], $not: {...} }
+ * 4. Nested relations: { relation: { field: value } }
+ */
+export type FilterCondition = {
+    [key: string]: any | z.infer<typeof FieldOperatorsSchema> | FilterCondition;
+} & {
+    /** Logical AND - combines all conditions that must be true */
+    $and?: FilterCondition[];
+    /** Logical OR - at least one condition must be true */
+    $or?: FilterCondition[];
+    /** Logical NOT - negates the condition */
+    $not?: FilterCondition;
+};
+/**
+ * Zod schema for recursive filter validation.
+ * Uses z.lazy() to handle recursive structure.
+ */
+export declare const FilterConditionSchema: z.ZodType<FilterCondition>;
+/**
+ * Top-level query filter wrapper.
+ * This is typically used as the "where" clause in a query.
+ *
+ * @example
+ * ```typescript
+ * const filter: QueryFilter = {
+ *   where: {
+ *     status: "active",                    // Implicit equality
+ *     age: { $gte: 18 },                   // Explicit operator
+ *     $or: [                               // Logical combination
+ *       { role: "admin" },
+ *       { email: { $contains: "@company.com" } }
+ *     ],
+ *     profile: {                           // Nested relation
+ *       verified: true
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const QueryFilterSchema: z.ZodObject<{
+    where: z.ZodOptional<z.ZodType<FilterCondition, z.ZodTypeDef, FilterCondition>>;
+}, "strip", z.ZodTypeAny, {
+    where?: FilterCondition | undefined;
+}, {
+    where?: FilterCondition | undefined;
+}>;
+/**
+ * Type-safe filter operators for use in TypeScript.
+ *
+ * @example
+ * ```typescript
+ * type UserFilter = Filter<User>;
+ *
+ * const filter: UserFilter = {
+ *   age: { $gte: 18 },
+ *   email: { $contains: "@example.com" }
+ * };
+ * ```
+ */
+export type Filter<T = any> = {
+    [K in keyof T]?: T[K] | {
+        $eq?: T[K];
+        $ne?: T[K];
+        $gt?: T[K] extends number | Date ? T[K] : never;
+        $gte?: T[K] extends number | Date ? T[K] : never;
+        $lt?: T[K] extends number | Date ? T[K] : never;
+        $lte?: T[K] extends number | Date ? T[K] : never;
+        $in?: T[K][];
+        $nin?: T[K][];
+        $between?: T[K] extends number | Date ? [T[K], T[K]] : never;
+        $contains?: T[K] extends string ? string : never;
+        $startsWith?: T[K] extends string ? string : never;
+        $endsWith?: T[K] extends string ? string : never;
+        $null?: boolean;
+        $exist?: boolean;
+    } | (T[K] extends object ? Filter<T[K]> : never);
+} & {
+    $and?: Filter<T>[];
+    $or?: Filter<T>[];
+    $not?: Filter<T>;
+};
+/**
+ * Scalar types supported by the filter system.
+ */
+export type Scalar = string | number | boolean | Date | null;
+export type FieldOperators = z.infer<typeof FieldOperatorsSchema>;
+export type QueryFilter = z.infer<typeof QueryFilterSchema>;
+/**
+ * Normalized filter AST structure.
+ * This is the internal representation after converting all syntactic sugar
+ * to explicit operators.
+ *
+ * Stage 1: Normalization Pass
+ * Input:  { age: 18, role: "admin" }
+ * Output: { $and: [{ age: { $eq: 18 } }, { role: { $eq: "admin" } }] }
+ *
+ * This simplifies adapter implementation by providing a consistent structure.
+ */
+export declare const NormalizedFilterSchema: z.ZodType<any>;
+export type NormalizedFilter = z.infer<typeof NormalizedFilterSchema>;
+/**
+ * All supported operator keys.
+ * Useful for validation and parsing.
+ */
+export declare const FILTER_OPERATORS: readonly ["$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin", "$between", "$contains", "$startsWith", "$endsWith", "$null", "$exist"];
+/**
+ * Logical operator keys.
+ */
+export declare const LOGICAL_OPERATORS: readonly ["$and", "$or", "$not"];
+/**
+ * All operator keys (field + logical).
+ */
+export declare const ALL_OPERATORS: readonly ["$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin", "$between", "$contains", "$startsWith", "$endsWith", "$null", "$exist", "$and", "$or", "$not"];
+export type FilterOperatorKey = typeof FILTER_OPERATORS[number];
+export type LogicalOperatorKey = typeof LOGICAL_OPERATORS[number];
+export type OperatorKey = typeof ALL_OPERATORS[number];
+//# sourceMappingURL=filter.zod.d.ts.map

package/dist/data/filter.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.zod.d.ts","sourceRoot":"","sources":["../../src/data/filter.zod.ts"],"names":[],"mappings":"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"}

package/dist/data/filter.zod.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_OPERATORS = exports.LOGICAL_OPERATORS = exports.FILTER_OPERATORS = exports.NormalizedFilterSchema = exports.QueryFilterSchema = exports.FilterConditionSchema = exports.FieldOperatorsSchema = exports.SpecialOperatorSchema = exports.StringOperatorSchema = exports.RangeOperatorSchema = exports.SetOperatorSchema = exports.ComparisonOperatorSchema = exports.EqualityOperatorSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Unified Query DSL Specification
+ *
+ * Based on industry best practices from:
+ * - Prisma ORM
+ * - Strapi CMS
+ * - TypeORM
+ * - LoopBack Framework
+ *
+ * Version: 1.0.0
+ * Status: Draft
+ *
+ * Objective: Define a JSON-based, database-agnostic query syntax standard
+ * for data filtering interactions between frontend and backend APIs.
+ *
+ * Design Principles:
+ * 1. Declarative: Frontend describes "what data to get", not "how to query"
+ * 2. Database Agnostic: Syntax contains no database-specific directives
+ * 3. Type Safe: Structure can be statically inferred by TypeScript
+ * 4. Convention over Configuration: Implicit syntax for common queries
+ */
+// ============================================================================
+// 3.1 Comparison Operators
+// ============================================================================
+/**
+ * Comparison operators for equality and inequality checks.
+ * Supported data types: Any
+ */
+exports.EqualityOperatorSchema = zod_1.z.object({
+    /** Equal to (default) - SQL: = | MongoDB: $eq */
+    $eq: zod_1.z.any().optional(),
+    /** Not equal to - SQL: <> or != | MongoDB: $ne */
+    $ne: zod_1.z.any().optional(),
+});
+/**
+ * Comparison operators for numeric and date comparisons.
+ * Supported data types: Number, Date
+ */
+exports.ComparisonOperatorSchema = zod_1.z.object({
+    /** Greater than - SQL: > | MongoDB: $gt */
+    $gt: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+    /** Greater than or equal to - SQL: >= | MongoDB: $gte */
+    $gte: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+    /** Less than - SQL: < | MongoDB: $lt */
+    $lt: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+    /** Less than or equal to - SQL: <= | MongoDB: $lte */
+    $lte: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+});
+// ============================================================================
+// 3.2 Set & Range Operators
+// ============================================================================
+/**
+ * Set operators for membership checks.
+ */
+exports.SetOperatorSchema = zod_1.z.object({
+    /** In list - SQL: IN (?, ?, ?) | MongoDB: $in */
+    $in: zod_1.z.array(zod_1.z.any()).optional(),
+    /** Not in list - SQL: NOT IN (...) | MongoDB: $nin */
+    $nin: zod_1.z.array(zod_1.z.any()).optional(),
+});
+/**
+ * Range operator for interval checks (closed interval).
+ * SQL: BETWEEN ? AND ? | MongoDB: $gte AND $lte
+ */
+exports.RangeOperatorSchema = zod_1.z.object({
+    /** Between (inclusive) - takes [min, max] array */
+    $between: zod_1.z.tuple([
+        zod_1.z.union([zod_1.z.number(), zod_1.z.date()]),
+        zod_1.z.union([zod_1.z.number(), zod_1.z.date()])
+    ]).optional(),
+});
+// ============================================================================
+// 3.3 String-Specific Operators
+// ============================================================================
+/**
+ * String pattern matching operators.
+ * Note: Case sensitivity should be handled at backend level.
+ */
+exports.StringOperatorSchema = zod_1.z.object({
+    /** Contains substring - SQL: LIKE %?% | MongoDB: $regex */
+    $contains: zod_1.z.string().optional(),
+    /** Starts with prefix - SQL: LIKE ?% | MongoDB: $regex */
+    $startsWith: zod_1.z.string().optional(),
+    /** Ends with suffix - SQL: LIKE %? | MongoDB: $regex */
+    $endsWith: zod_1.z.string().optional(),
+});
+// ============================================================================
+// 3.5 Special Operators
+// ============================================================================
+/**
+ * Special check operators for null and existence.
+ */
+exports.SpecialOperatorSchema = zod_1.z.object({
+    /** Is null check - SQL: IS NULL (true) / IS NOT NULL (false) | MongoDB: field: null */
+    $null: zod_1.z.boolean().optional(),
+    /** Field exists check (primarily for NoSQL) - MongoDB: $exists */
+    $exist: zod_1.z.boolean().optional(),
+});
+// ============================================================================
+// Combined Field Operators
+// ============================================================================
+/**
+ * All field-level operators combined.
+ * These can be applied to individual fields in a filter.
+ */
+exports.FieldOperatorsSchema = zod_1.z.object({
+    // Equality
+    $eq: zod_1.z.any().optional(),
+    $ne: zod_1.z.any().optional(),
+    // Comparison (numeric/date)
+    $gt: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+    $gte: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+    $lt: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+    $lte: zod_1.z.union([zod_1.z.number(), zod_1.z.date()]).optional(),
+    // Set & Range
+    $in: zod_1.z.array(zod_1.z.any()).optional(),
+    $nin: zod_1.z.array(zod_1.z.any()).optional(),
+    $between: zod_1.z.tuple([
+        zod_1.z.union([zod_1.z.number(), zod_1.z.date()]),
+        zod_1.z.union([zod_1.z.number(), zod_1.z.date()])
+    ]).optional(),
+    // String-specific
+    $contains: zod_1.z.string().optional(),
+    $startsWith: zod_1.z.string().optional(),
+    $endsWith: zod_1.z.string().optional(),
+    // Special
+    $null: zod_1.z.boolean().optional(),
+    $exist: zod_1.z.boolean().optional(),
+});
+/**
+ * Zod schema for recursive filter validation.
+ * Uses z.lazy() to handle recursive structure.
+ */
+exports.FilterConditionSchema = zod_1.z.lazy(() => zod_1.z.record(zod_1.z.string(), zod_1.z.any()).and(zod_1.z.object({
+    $and: zod_1.z.array(exports.FilterConditionSchema).optional(),
+    $or: zod_1.z.array(exports.FilterConditionSchema).optional(),
+    $not: exports.FilterConditionSchema.optional(),
+})));
+// ============================================================================
+// Query Filter Wrapper
+// ============================================================================
+/**
+ * Top-level query filter wrapper.
+ * This is typically used as the "where" clause in a query.
+ *
+ * @example
+ * ```typescript
+ * const filter: QueryFilter = {
+ *   where: {
+ *     status: "active",                    // Implicit equality
+ *     age: { $gte: 18 },                   // Explicit operator
+ *     $or: [                               // Logical combination
+ *       { role: "admin" },
+ *       { email: { $contains: "@company.com" } }
+ *     ],
+ *     profile: {                           // Nested relation
+ *       verified: true
+ *     }
+ *   }
+ * }
+ * ```
+ */
+exports.QueryFilterSchema = zod_1.z.object({
+    where: exports.FilterConditionSchema.optional(),
+});
+// ============================================================================
+// Normalization Utilities (Internal Representation)
+// ============================================================================
+/**
+ * Normalized filter AST structure.
+ * This is the internal representation after converting all syntactic sugar
+ * to explicit operators.
+ *
+ * Stage 1: Normalization Pass
+ * Input:  { age: 18, role: "admin" }
+ * Output: { $and: [{ age: { $eq: 18 } }, { role: { $eq: "admin" } }] }
+ *
+ * This simplifies adapter implementation by providing a consistent structure.
+ */
+exports.NormalizedFilterSchema = zod_1.z.lazy(() => zod_1.z.object({
+    $and: zod_1.z.array(zod_1.z.union([
+        // Field condition: { field: { $op: value } }
+        zod_1.z.record(zod_1.z.string(), exports.FieldOperatorsSchema),
+        // Nested logical group
+        exports.NormalizedFilterSchema,
+    ])).optional(),
+    $or: zod_1.z.array(zod_1.z.union([
+        zod_1.z.record(zod_1.z.string(), exports.FieldOperatorsSchema),
+        exports.NormalizedFilterSchema,
+    ])).optional(),
+    $not: zod_1.z.union([
+        zod_1.z.record(zod_1.z.string(), exports.FieldOperatorsSchema),
+        exports.NormalizedFilterSchema,
+    ]).optional(),
+}));
+// ============================================================================
+// Constants & Metadata
+// ============================================================================
+/**
+ * All supported operator keys.
+ * Useful for validation and parsing.
+ */
+exports.FILTER_OPERATORS = [
+    // Equality
+    '$eq', '$ne',
+    // Comparison
+    '$gt', '$gte', '$lt', '$lte',
+    // Set & Range
+    '$in', '$nin', '$between',
+    // String
+    '$contains', '$startsWith', '$endsWith',
+    // Special
+    '$null', '$exist',
+];
+/**
+ * Logical operator keys.
+ */
+exports.LOGICAL_OPERATORS = ['$and', '$or', '$not'];
+/**
+ * All operator keys (field + logical).
+ */
+exports.ALL_OPERATORS = [...exports.FILTER_OPERATORS, ...exports.LOGICAL_OPERATORS];

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from './data/workflow.zod';
 export * from './data/flow.zod';
 export * from './data/dataset.zod';
 export * from './data/query.zod';
+export * from './data/filter.zod';
 export * from './data/mapping.zod';
 export * from './data/trigger.zod';
 export * from './api/contract.zod';
@@ -31,6 +32,7 @@ export * from './system/manifest.zod';
 export * from './system/datasource.zod';
 export * from './system/api.zod';
 export * from './system/identity.zod';
+export * from './system/auth.zod';
 export * from './system/policy.zod';
 export * from './system/role.zod';
 export * from './system/territory.zod';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -32,6 +32,7 @@ __exportStar(require("./data/workflow.zod"), exports);
 __exportStar(require("./data/flow.zod"), exports);
 __exportStar(require("./data/dataset.zod"), exports);
 __exportStar(require("./data/query.zod"), exports);
+__exportStar(require("./data/filter.zod"), exports); // Unified Query DSL
 __exportStar(require("./data/mapping.zod"), exports);
 __exportStar(require("./data/trigger.zod"), exports);
 // API Protocol (Envelopes, Contracts)
@@ -52,6 +53,7 @@ __exportStar(require("./system/manifest.zod"), exports);
 __exportStar(require("./system/datasource.zod"), exports);
 __exportStar(require("./system/api.zod"), exports);
 __exportStar(require("./system/identity.zod"), exports);
+__exportStar(require("./system/auth.zod"), exports);
 __exportStar(require("./system/policy.zod"), exports);
 __exportStar(require("./system/role.zod"), exports);
 __exportStar(require("./system/territory.zod"), exports);