@wildo-ai/saas-models 1.0.1

package/dist/esm/resources/context-policy.shared.schemas.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Context Policy Shared Schemas
+ *
+ * Defines how related resources are fetched when traversing relationships.
+ * Used by ResourceContextBackendService to determine fetch behavior.
+ *
+ * Design Principle: "Decorators describe structure. Relationships describe traversal."
+ */
+import { z } from 'zod';
+import { CoreResourceOperation } from './resources.shared.core.definitions.js';
+/**
+ * Object mode for relationship data in context.
+ * Determines what level of detail is fetched for related resources.
+ */
+export declare enum ContextPolicy_ObjectMode {
+    /** Include complete resource object (all fields) */
+    FULL = "FULL",
+    /** Include only fields marked with isSummaryField() decorator */
+    SUMMARY = "SUMMARY",
+    /** Include only the ID reference - no database fetch */
+    ID_ONLY = "ID_ONLY"
+}
+/**
+ * Access rights mode for context relationships.
+ * Determines how user permissions filter related resources.
+ */
+export declare enum ContextPolicy_AccessRightsMode {
+    /** Include all resources regardless of user permissions */
+    ALL = "ALL",
+    /** Only include resources user has read access to */
+    USER_FILTERED = "USER_FILTERED",
+    /** Only include resources user has write access to */
+    WRITE_FILTERED = "WRITE_FILTERED"
+}
+/**
+ * Per-operation context policy override.
+ * Allows different context behavior for READ vs LIST vs CREATE, etc.
+ */
+export interface ContextPolicy_OperationOverride {
+    /** Override enabled state for this operation */
+    enabled?: boolean;
+    /** Override depth for this operation */
+    depth?: number;
+    /** Override object mode for this operation */
+    objectMode?: ContextPolicy_ObjectMode;
+    /** Override access rights mode for this operation */
+    accessRightsMode?: ContextPolicy_AccessRightsMode;
+}
+/**
+ * Context policy for a relationship.
+ * Defines how related resources are fetched when traversing this relationship.
+ *
+ * @example Basic usage - uses all defaults
+ * ```typescript
+ * contextPolicy: {}  // enabled=true, depth=1, objectMode=SUMMARY
+ * ```
+ *
+ * @example Disable context for security (credentials, secrets, API keys)
+ * ```typescript
+ * contextPolicy: { enabled: false }
+ * ```
+ *
+ * @example Full data on READ, summary on LIST (1:1 profile/preferences)
+ * ```typescript
+ * contextPolicy: {
+ *   objectMode: ContextPolicy_ObjectMode.SUMMARY,
+ *   operationOverrides: {
+ *     [CoreResourceOperation.READ]: { objectMode: ContextPolicy_ObjectMode.FULL }
+ *   }
+ * }
+ * ```
+ *
+ * @example Disable on LIST/SEARCH for performance (high-cardinality relationships)
+ * ```typescript
+ * contextPolicy: {
+ *   operationOverrides: {
+ *     [CoreResourceOperation.LIST]: { enabled: false },
+ *     [CoreResourceOperation.SEARCH]: { enabled: false }
+ *   }
+ * }
+ * ```
+ *
+ * @example Self-referencing relationships (prevent infinite loops)
+ * ```typescript
+ * contextPolicy: {
+ *   objectMode: ContextPolicy_ObjectMode.ID_ONLY,
+ *   depth: 1
+ * }
+ * ```
+ */
+export interface RelationshipContextPolicy {
+    /**
+     * Whether context fetching is enabled for this relationship.
+     * Set to false to completely skip fetching related resources.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Depth of traversal through this relationship.
+     * - 0: Don't fetch (same as enabled: false)
+     * - 1: Fetch direct relationship only (default)
+     * - 2: Fetch related resource AND its direct relationships
+     * - 3: Maximum allowed depth (use with caution)
+     *
+     * Higher depths have exponential performance implications.
+     * @default 1
+     */
+    depth?: number;
+    /**
+     * What data to include from the related resource.
+     * - FULL: Complete resource object (all fields)
+     * - SUMMARY: Only fields marked with isSummaryField() decorator
+     * - ID_ONLY: Just the ID reference, no actual fetch
+     * @default SUMMARY
+     */
+    objectMode?: ContextPolicy_ObjectMode;
+    /**
+     * Access rights filtering for the related resource.
+     * Controls whether user permissions affect what's returned.
+     * @default USER_FILTERED
+     */
+    accessRightsMode?: ContextPolicy_AccessRightsMode;
+    /**
+     * Per-operation overrides.
+     * Allows different context behavior for specific operations.
+     * Keys are limited to `CoreResourceOperation` values.
+     *
+     * Common patterns:
+     * - Disable on LIST/SEARCH for performance
+     * - Use FULL on READ for detail views
+     * - Disable on CREATE for validation-only
+     */
+    operationOverrides?: Partial<Record<CoreResourceOperation, ContextPolicy_OperationOverride>>;
+}
+/**
+ * Default context policy when not specified on relationship.
+ * Conservative defaults optimized for common use cases.
+ */
+export declare const DEFAULT_RELATIONSHIP_CONTEXT_POLICY: Required<Omit<RelationshipContextPolicy, 'operationOverrides'>>;
+export declare const ContextPolicy_OperationOverrideSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    objectMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_ObjectMode>>;
+    accessRightsMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_AccessRightsMode>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export type ContextPolicy_OperationOverrideType = z.infer<typeof ContextPolicy_OperationOverrideSchema>;
+export declare const RelationshipContextPolicySchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    objectMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_ObjectMode>>;
+    accessRightsMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_AccessRightsMode>>;
+    operationOverrides: z.ZodOptional<z.ZodRecord<z.ZodEnum<typeof CoreResourceOperation> & z.core.$partial, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        objectMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_ObjectMode>>;
+        accessRightsMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_AccessRightsMode>>;
+    }, z.core.$strip, core.$ZodObjectExtra>>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+//# sourceMappingURL=context-policy.shared.schemas.d.ts.map

package/dist/esm/resources/context-policy.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-policy.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/resources/context-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAM5E;;;GAGG;AACH,oBAAY,wBAAwB;IAClC,oDAAoD;IACpD,IAAI,SAAS;IACb,iEAAiE;IACjE,OAAO,YAAY;IACnB,wDAAwD;IACxD,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,oBAAY,8BAA8B;IACxC,2DAA2D;IAC3D,GAAG,QAAQ;IACX,qDAAqD;IACrD,aAAa,kBAAkB;IAC/B,sDAAsD;IACtD,cAAc,mBAAmB;CAClC;AAMD;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,wBAAwB,CAAC;IAEtC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;IAElD;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CACjC,qBAAqB,EACrB,+BAA+B,CAChC,CAAC,CAAC;CACJ;AAMD;;;GAGG;AACH,eAAO,MAAM,mCAAmC,EAAE,QAAQ,CACxD,IAAI,CAAC,yBAAyB,EAAE,oBAAoB,CAAC,CAMtD,CAAC;AAMF,eAAO,MAAM,qCAAqC;;;;;uCAKhD,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAExG,eAAO,MAAM,+BAA+B;;;;;;;;;;;uCAS1C,CAAC"}

package/dist/esm/resources/context-policy.shared.schemas.js

@@ -0,0 +1,69 @@
+/**
+ * Context Policy Shared Schemas
+ *
+ * Defines how related resources are fetched when traversing relationships.
+ * Used by ResourceContextBackendService to determine fetch behavior.
+ *
+ * Design Principle: "Decorators describe structure. Relationships describe traversal."
+ */
+import { z } from 'zod';
+import { CoreResourceOperation } from './resources.shared.core.definitions.js';
+// =============================================================================
+// ENUMS
+// =============================================================================
+/**
+ * Object mode for relationship data in context.
+ * Determines what level of detail is fetched for related resources.
+ */
+export var ContextPolicy_ObjectMode;
+(function (ContextPolicy_ObjectMode) {
+    /** Include complete resource object (all fields) */
+    ContextPolicy_ObjectMode["FULL"] = "FULL";
+    /** Include only fields marked with isSummaryField() decorator */
+    ContextPolicy_ObjectMode["SUMMARY"] = "SUMMARY";
+    /** Include only the ID reference - no database fetch */
+    ContextPolicy_ObjectMode["ID_ONLY"] = "ID_ONLY";
+})(ContextPolicy_ObjectMode || (ContextPolicy_ObjectMode = {}));
+/**
+ * Access rights mode for context relationships.
+ * Determines how user permissions filter related resources.
+ */
+export var ContextPolicy_AccessRightsMode;
+(function (ContextPolicy_AccessRightsMode) {
+    /** Include all resources regardless of user permissions */
+    ContextPolicy_AccessRightsMode["ALL"] = "ALL";
+    /** Only include resources user has read access to */
+    ContextPolicy_AccessRightsMode["USER_FILTERED"] = "USER_FILTERED";
+    /** Only include resources user has write access to */
+    ContextPolicy_AccessRightsMode["WRITE_FILTERED"] = "WRITE_FILTERED";
+})(ContextPolicy_AccessRightsMode || (ContextPolicy_AccessRightsMode = {}));
+// =============================================================================
+// DEFAULTS
+// =============================================================================
+/**
+ * Default context policy when not specified on relationship.
+ * Conservative defaults optimized for common use cases.
+ */
+export const DEFAULT_RELATIONSHIP_CONTEXT_POLICY = {
+    enabled: true,
+    depth: 1,
+    objectMode: ContextPolicy_ObjectMode.SUMMARY,
+    accessRightsMode: ContextPolicy_AccessRightsMode.USER_FILTERED,
+};
+// =============================================================================
+// ZOD SCHEMAS (for validation)
+// =============================================================================
+export const ContextPolicy_OperationOverrideSchema = z.object({
+    enabled: z.boolean().optional(),
+    depth: z.number().int().min(0).max(3).optional(),
+    objectMode: z.enum(ContextPolicy_ObjectMode).optional(),
+    accessRightsMode: z.enum(ContextPolicy_AccessRightsMode).optional(),
+});
+export const RelationshipContextPolicySchema = z.object({
+    enabled: z.boolean().optional(),
+    depth: z.number().int().min(0).max(3).optional(),
+    objectMode: z.enum(ContextPolicy_ObjectMode).optional(),
+    accessRightsMode: z.enum(ContextPolicy_AccessRightsMode).optional(),
+    operationOverrides: z.partialRecord(z.enum(CoreResourceOperation), ContextPolicy_OperationOverrideSchema).optional(),
+});
+//# sourceMappingURL=context-policy.shared.schemas.js.map

package/dist/esm/resources/context-policy.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-policy.shared.schemas.js","sourceRoot":"","sources":["../../../src/resources/context-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,gFAAgF;AAChF,QAAQ;AACR,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAN,IAAY,wBAOX;AAPD,WAAY,wBAAwB;IAClC,oDAAoD;IACpD,yCAAa,CAAA;IACb,iEAAiE;IACjE,+CAAmB,CAAA;IACnB,wDAAwD;IACxD,+CAAmB,CAAA;AACrB,CAAC,EAPW,wBAAwB,KAAxB,wBAAwB,QAOnC;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,8BAOX;AAPD,WAAY,8BAA8B;IACxC,2DAA2D;IAC3D,6CAAW,CAAA;IACX,qDAAqD;IACrD,iEAA+B,CAAA;IAC/B,sDAAsD;IACtD,mEAAiC,CAAA;AACnC,CAAC,EAPW,8BAA8B,KAA9B,8BAA8B,QAOzC;AAmHD,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAE5C;IACF,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,CAAC;IACR,UAAU,EAAE,wBAAwB,CAAC,OAAO;IAC5C,gBAAgB,EAAE,8BAA8B,CAAC,aAAa;CAC/D,CAAC;AAEF,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAEhF,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5D,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;IACvD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,QAAQ,EAAE;CACpE,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;IACvD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,QAAQ,EAAE;IACnE,kBAAkB,EAAE,CAAC,CAAC,aAAa,CACjC,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,EAC7B,qCAAqC,CACtC,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC"}