@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/organizations/organization-units.shared.schemas.js

@@ -2,9 +2,21 @@
  * Organization Unit Shared Schemas
  *
  * Hierarchical organizational structures for enterprise access control.
- * Supports nested organizational units with inheritance rules and permission propagation.
+ * Supports nested organizational units with downward-only permission-inheritance rules.
+ *
+ * Units ARE an authorization axis (WS-C, shipped 2026-08-01): a member's per-unit role is emitted
+ * into `initiatorRoles` as a narrowed grant, and for resources that opt into unit narrowing it admits
+ * the member at the operation gate and confines their rows to the units that grant covers —
+ * propagating to descendants where {@link OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN}
+ * says so. A unit is a NARROWING dimension inside `ResourcePrimaryScope.ORGANIZATIONS`, never a scope
+ * of its own (decision D-C1), so tenant isolation is unchanged.
+ *
+ * Narrowing is strictly opt-in per resource and ADDITIVE: an organization-wide role that already
+ * satisfies an operation is never confined. See
+ * `.claude/plans/tenant-teardown-and-organization-units-domain.md` (WS-C).
  */
 import { z } from 'zod';
+import { ErrorCustomMessageReference } from '../errors/errors.custom-message-ref.shared.definitions.js';
 // ===============================
 // ORGANIZATION UNIT ENUMS
 // ===============================
@@ -30,29 +42,101 @@ export var OrganizationUnitStatus;
     OrganizationUnitStatus["ARCHIVED"] = "archived";
     OrganizationUnitStatus["SUSPENDED"] = "suspended";
 })(OrganizationUnitStatus || (OrganizationUnitStatus = {}));
+/**
+ * Direction in which a role held at one unit propagates across that unit's hierarchy edges.
+ *
+ * DOWNWARD ONLY, BY DESIGN. Only two directions exist, and that is a deliberate security
+ * constraint rather than an unfinished vocabulary. A role granted at a unit may widen to that
+ * unit's DESCENDANTS (the intuitive "a division manager manages its teams") or to nothing at all.
+ *
+ * `INHERIT_UP` and `BOTH_DIRECTIONS` were REMOVED (2026-07-31, decision D-C2). Upward propagation
+ * means a role held at a leaf confers authority over its ANCESTORS — a team lead acquiring
+ * division-wide authority by virtue of sitting inside it. That is privilege escalation along the
+ * org chart, and it is the exact shape the role-ceiling gate
+ * (`assertRequestedRolesWithinCallerCeiling`) exists to prevent on every other role-granting
+ * surface; offering it as a one-field toggle here would have re-opened it structurally.
+ *
+ * If upward VISIBILITY is genuinely needed ("a division head sees rolled-up team data"), model it
+ * as a reporting/aggregation concern — a read projection over the subtree — NOT as role
+ * propagation. The two are different semantics and merging them costs the fail-closed guarantee.
+ *
+ * ENFORCED since 2026-08-01 (WS-C phase 3). The authorization gate expands a unit-scoped grant across
+ * this edge before stamping it on the execution context, so the value governs how far the grant
+ * actually reaches on every narrowed resource — read and write alike. The expansion is a PREFIX test
+ * over the materialized `path`, never a recursive walk.
+ *
+ * ⚠️ Enforcement reads this field literally: an ABSENT value is treated as `NO_INHERITANCE`, which
+ * deliberately differs from the write-time default below. A row reaching an authorization decision
+ * without the field bypassed the schema that would have supplied that default, and a grant must never
+ * widen on data the authorizer cannot vouch for.
+ *
+ * ⚠️ A grant at a ROOT unit with downward inheritance reaches the entire chart — functionally
+ * organization-wide access assembled from one narrow grant. That is sound under the additive model but
+ * must stay legible, which is why the access record reports directly-held and inherited units
+ * separately (decision D-C4, watch item 4).
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — least-privilege by construction: the
+ * vocabulary cannot express an upward privilege grant.
+ */
 export var OrganizationUnit_PermissionInheritanceType;
 (function (OrganizationUnit_PermissionInheritanceType) {
+    /** A role held at this unit also applies to its descendant units. */
     OrganizationUnit_PermissionInheritanceType["INHERIT_DOWN"] = "inherit_down";
-    OrganizationUnit_PermissionInheritanceType["INHERIT_UP"] = "inherit_up";
+    /** A role held at this unit applies to this unit only; the node is isolated for permission purposes. */
     OrganizationUnit_PermissionInheritanceType["NO_INHERITANCE"] = "no_inheritance";
-    OrganizationUnit_PermissionInheritanceType["BOTH_DIRECTIONS"] = "both_directions"; // Inherit both up and down
 })(OrganizationUnit_PermissionInheritanceType || (OrganizationUnit_PermissionInheritanceType = {}));
+/**
+ * A node of an organization's tree.
+ *
+ * **Business key — `code` is unique among siblings.** Declared here rather than only in the
+ * application guard because the guard is a read-then-write: two concurrent CREATEs of the same code
+ * under the same parent can each find nothing and each succeed. The compound index closes that
+ * window at the database.
+ *
+ * ⚠️ The index is a **MongoDB-only** guarantee today. The SQL planner records uniqueness as intent
+ * and leaves enforcement migration-owned, so the application guard in the unit custom
+ * implementation is KEPT as the cross-adapter backstop rather than deleted as redundant. The two
+ * raise the same {@link ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS} so a client sees
+ * one code for one condition, whichever layer catches it.
+ */
 export const OrganizationUnitSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
     organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
-    parentUnitId: z.string().optional().isDBIndexed().isForeignKey(),
+    /**
+     * The parent node of this unit; absent on a root that hangs directly under the organization.
+     *
+     * `.excludeFromUpdate()` (plan decision D-B2): re-parenting is owned exclusively by the MOVE
+     * operation. A reparent has a subtree-wide side effect — every descendant's materialized
+     * {@link OrganizationUnitSchema.shape.path} has to be rewritten — and it must be refused when the
+     * destination sits inside the moved node's own subtree. Generic UPDATE performs neither, so
+     * allowing it here would silently produce a tree whose paths describe a shape that no longer
+     * exists, or a detached cycle. One operation, one authority.
+     */
+    parentUnitId: z.string().optional().isDBIndexed().isForeignKey().excludeFromUpdate(),
     status: z.enum(OrganizationUnitStatus).default(OrganizationUnitStatus.ACTIVE).isDBIndexed().isSummaryField(),
     inheritanceType: z.enum(OrganizationUnit_PermissionInheritanceType).default(OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN).isDBIndexed(),
     path: z.string().isDBIndexed().excludeFromCreate().excludeFromUpdate(),
     // Unit Identity
     name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),
+    /**
+     * Short human-assigned handle for the unit, unique among its siblings — see the
+     * {@link OrganizationUnitSchema} business key below for the exact scope and why it is optional.
+     */
     code: z.string().min(1).max(20).optional(),
     type: z.enum(OrganizationUnitType).optional().isDBIndexed().isSummaryField(),
     createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+}).businessKeySet(['organizationId', 'parentUnitId', 'code'], {
+    // A row with no `code` has no key at all, so it must sit OUTSIDE the constraint: any number of
+    // code-less siblings under one parent is legitimate. `parentUnitId` is deliberately NOT listed
+    // — an absent parent means "root", which is a real position in the tree, so roots must still
+    // collide with each other. Listing it would exclude every root from the index and quietly lose
+    // uniqueness for exactly the nodes an org chart starts with.
+    skipRowsMissing: ['code'],
+    conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS,
 });
 export const OrganizationUnitTreeNodeSchema = z.object({
     unit: OrganizationUnitSchema,
     children: z.array(z.lazy(() => OrganizationUnitTreeNodeSchema)).default([]),
 });
-//# sourceMappingURL=organization-units.shared.schemas.js.map
+//# sourceMappingURL=organization-units.shared.schemas.js.map

package/dist/esm/organizations/organization-units.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"organization-units.shared.schemas.js","sourceRoot":"","sources":["../../../src/organizations/organization-units.shared.schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"organization-units.shared.schemas.js","sourceRoot":"","sources":["../../../../src/organizations/organization-units.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Organization Unit Shared Schemas\n * \n * Hierarchical organizational structures for enterprise access control.\n * Supports nested organizational units with downward-only permission-inheritance rules.\n *\n * Units ARE an authorization axis (WS-C, shipped 2026-08-01): a member's per-unit role is emitted\n * into `initiatorRoles` as a narrowed grant, and for resources that opt into unit narrowing it admits\n * the member at the operation gate and confines their rows to the units that grant covers —\n * propagating to descendants where {@link OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN}\n * says so. A unit is a NARROWING dimension inside `ResourcePrimaryScope.ORGANIZATIONS`, never a scope\n * of its own (decision D-C1), so tenant isolation is unchanged.\n *\n * Narrowing is strictly opt-in per resource and ADDITIVE: an organization-wide role that already\n * satisfies an operation is never confined. See\n * `.claude/plans/tenant-teardown-and-organization-units-domain.md` (WS-C).\n */\n\nimport { z } from 'zod';\n\nimport { ErrorCustomMessageReference } from '../errors/errors.custom-message-ref.shared.definitions';\n\n// ===============================\n// ORGANIZATION UNIT ENUMS\n// ===============================\n\n/**\n * Organization unit type enum\n */\nexport enum OrganizationUnitType {\n  COMPANY = 'company',\n  DIVISION = 'division',\n  DEPARTMENT = 'department',\n  TEAM = 'team',\n  SUBTEAM = 'subteam',\n  PROJECT_GROUP = 'project_group',\n  GEOGRAPHIC = 'geographic',\n  FUNCTIONAL = 'functional',\n  CUSTOM = 'custom'\n}\n\nexport enum OrganizationUnitStatus {\n  ACTIVE = 'active',\n  INACTIVE = 'inactive',\n  ARCHIVED = 'archived',\n  SUSPENDED = 'suspended'\n}\n\n/**\n * Direction in which a role held at one unit propagates across that unit's hierarchy edges.\n *\n * DOWNWARD ONLY, BY DESIGN. Only two directions exist, and that is a deliberate security\n * constraint rather than an unfinished vocabulary. A role granted at a unit may widen to that\n * unit's DESCENDANTS (the intuitive \"a division manager manages its teams\") or to nothing at all.\n *\n * `INHERIT_UP` and `BOTH_DIRECTIONS` were REMOVED (2026-07-31, decision D-C2). Upward propagation\n * means a role held at a leaf confers authority over its ANCESTORS — a team lead acquiring\n * division-wide authority by virtue of sitting inside it. That is privilege escalation along the\n * org chart, and it is the exact shape the role-ceiling gate\n * (`assertRequestedRolesWithinCallerCeiling`) exists to prevent on every other role-granting\n * surface; offering it as a one-field toggle here would have re-opened it structurally.\n *\n * If upward VISIBILITY is genuinely needed (\"a division head sees rolled-up team data\"), model it\n * as a reporting/aggregation concern — a read projection over the subtree — NOT as role\n * propagation. The two are different semantics and merging them costs the fail-closed guarantee.\n *\n * ENFORCED since 2026-08-01 (WS-C phase 3). The authorization gate expands a unit-scoped grant across\n * this edge before stamping it on the execution context, so the value governs how far the grant\n * actually reaches on every narrowed resource — read and write alike. The expansion is a PREFIX test\n * over the materialized `path`, never a recursive walk.\n *\n * ⚠️ Enforcement reads this field literally: an ABSENT value is treated as `NO_INHERITANCE`, which\n * deliberately differs from the write-time default below. A row reaching an authorization decision\n * without the field bypassed the schema that would have supplied that default, and a grant must never\n * widen on data the authorizer cannot vouch for.\n *\n * ⚠️ A grant at a ROOT unit with downward inheritance reaches the entire chart — functionally\n * organization-wide access assembled from one narrow grant. That is sound under the additive model but\n * must stay legible, which is why the access record reports directly-held and inherited units\n * separately (decision D-C4, watch item 4).\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — least-privilege by construction: the\n * vocabulary cannot express an upward privilege grant.\n */\nexport enum OrganizationUnit_PermissionInheritanceType {\n  /** A role held at this unit also applies to its descendant units. */\n  INHERIT_DOWN = 'inherit_down',\n  /** A role held at this unit applies to this unit only; the node is isolated for permission purposes. */\n  NO_INHERITANCE = 'no_inheritance',\n}\n\n\n/**\n * A node of an organization's tree.\n *\n * **Business key — `code` is unique among siblings.** Declared here rather than only in the\n * application guard because the guard is a read-then-write: two concurrent CREATEs of the same code\n * under the same parent can each find nothing and each succeed. The compound index closes that\n * window at the database.\n *\n * ⚠️ The index is a **MongoDB-only** guarantee today. The SQL planner records uniqueness as intent\n * and leaves enforcement migration-owned, so the application guard in the unit custom\n * implementation is KEPT as the cross-adapter backstop rather than deleted as redundant. The two\n * raise the same {@link ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS} so a client sees\n * one code for one condition, whichever layer catches it.\n */\nexport const OrganizationUnitSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n  /**\n   * The parent node of this unit; absent on a root that hangs directly under the organization.\n   *\n   * `.excludeFromUpdate()` (plan decision D-B2): re-parenting is owned exclusively by the MOVE\n   * operation. A reparent has a subtree-wide side effect — every descendant's materialized\n   * {@link OrganizationUnitSchema.shape.path} has to be rewritten — and it must be refused when the\n   * destination sits inside the moved node's own subtree. Generic UPDATE performs neither, so\n   * allowing it here would silently produce a tree whose paths describe a shape that no longer\n   * exists, or a detached cycle. One operation, one authority.\n   */\n  parentUnitId: z.string().optional().isDBIndexed().isForeignKey().excludeFromUpdate(),\n  status: z.enum(OrganizationUnitStatus).default(OrganizationUnitStatus.ACTIVE).isDBIndexed().isSummaryField(),\n  inheritanceType: z.enum(OrganizationUnit_PermissionInheritanceType).default(OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN).isDBIndexed(),\n  \n  path: z.string().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  \n  // Unit Identity\n  name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),\n  /**\n   * Short human-assigned handle for the unit, unique among its siblings — see the\n   * {@link OrganizationUnitSchema} business key below for the exact scope and why it is optional.\n   */\n  code: z.string().min(1).max(20).optional(),\n  type: z.enum(OrganizationUnitType).optional().isDBIndexed().isSummaryField(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n}).businessKeySet(\n  ['organizationId', 'parentUnitId', 'code'],\n  {\n    // A row with no `code` has no key at all, so it must sit OUTSIDE the constraint: any number of\n    // code-less siblings under one parent is legitimate. `parentUnitId` is deliberately NOT listed\n    // — an absent parent means \"root\", which is a real position in the tree, so roots must still\n    // collide with each other. Listing it would exclude every root from the index and quietly lose\n    // uniqueness for exactly the nodes an org chart starts with.\n    skipRowsMissing: ['code'],\n    conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS,\n  },\n);\nexport type OrganizationUnit = z.infer<typeof OrganizationUnitSchema>;\n\n// RECURSIVE type - keep explicit interface\nexport interface OrganizationUnitTreeNode {\n  unit: OrganizationUnit;\n  children: OrganizationUnitTreeNode[];\n}\n\nexport const OrganizationUnitTreeNodeSchema: z.ZodType<OrganizationUnitTreeNode> = z.object({\n  unit: OrganizationUnitSchema,\n  children: z.array(z.lazy(() => OrganizationUnitTreeNodeSchema)).default([]),\n});\n\n"]}

package/dist/esm/organizations/organizations.shared.resources-config.schemas.d.ts

@@ -5,23 +5,58 @@
  * Separated into App Admin concerns and Organization self-management.
  */
 import { z } from 'zod';
-import { OrganizationStatus } from './organizations.shared.schemas.js';
-import { CoreResourceOperation } from '../resources/resources.shared.core.definitions.js';
-import { ResourceRelationship } from '../resources/resources.shared.schemas.js';
-export declare enum Organization_AppAdmin_Operations {
+import { OrganizationStatus } from './organizations.shared.schemas';
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+import { ResourceRelationship } from '../resources/resources.shared.schemas';
+/**
+ * Tenant LIFECYCLE transitions — the operations that own `Organization.status`.
+ *
+ * Renamed from `Organization_AppAdmin_Operations` on 2026-08-01. The old name described the
+ * AUDIENCE of the two members it happened to hold (`ACTIVATE`/`SUSPEND` are super-admin-only) and
+ * stopped being true the moment an ORG_ADMIN-facing member joined it. The members share a
+ * *concern*, not an audience: each is a guarded transition of the tenant state machine, declared
+ * `resourceOperationLike: UPDATE`, gated by an `enabledCondition` on the current status, and the
+ * sole authority for the `status` field that generic UPDATE may not write. The frontend already
+ * called this concept by its right name — `organizationLifecycleOpViews` in the presets.
+ *
+ * `status` is `.excludeFromUpdate()`, so every transition here declares `authoritativeFields`
+ * naming the fields its prefix owns; without that the repository's strict re-parse silently strips
+ * the write and the operation answers success having changed nothing.
+ */
+export declare enum Organization_Lifecycle_Operations {
     ACTIVATE = "activate",
-    SUSPEND = "suspend"
+    SUSPEND = "suspend",
+    /**
+     * Mark the tenant for deletion — the SOFT-DELETE half of tenant teardown.
+     *
+     * Replaces the tenant-facing `DELETE` door, which now belongs to the purge batch. Writes
+     * `status: DELETED` + `deletionRequestedAt` + `purgeScheduledAt`, reconciles every affected user's global
+     * `userTypes`, and invalidates their tokens — so the tenant is authorization-dead immediately
+     * while remaining fully data-alive and restorable until the window elapses.
+     */
+    REQUEST_DELETION = "request_deletion",
+    /**
+     * Cancel a pending deletion inside the retention window.
+     *
+     * The inverse of {@link REQUEST_DELETION}. Nothing needs re-creating: authority is re-derived
+     * from the membership rows the window deliberately preserved, which is exactly why those rows
+     * are not touched at mark time.
+     */
+    RESTORE = "restore"
 }
 type OrganizationCoreOperations = CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.SEARCH | CoreResourceOperation.CREATE | CoreResourceOperation.UPDATE | CoreResourceOperation.DELETE;
-export declare const organizationResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("../index.js").ResourceConfiguration<typeof Organization_AppAdmin_Operations, OrganizationCoreOperations, z.ZodObject<{
+export declare const organizationResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("..").ResourceConfiguration<typeof Organization_Lifecycle_Operations, OrganizationCoreOperations, z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     name: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
-    type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
-    slug: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
-    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof OrganizationStatus>>>>;
+    type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    slug: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof OrganizationStatus>>>>>;
+    platformAccessApprovalRequired: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
-    deletedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
-}, z.core.$strip, core.$ZodObjectExtra>>;
+    deletionRequestedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodNullable<z.ZodDate>>>>>>;
+    ownerFloorSerializationToken: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>>>>;
+    purgeScheduledAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodNullable<z.ZodDate>>>>>>;
+}, z.core.$strip>>;
 export {};
 //# sourceMappingURL=organizations.shared.resources-config.schemas.d.ts.map

package/dist/esm/organizations/organizations.shared.resources-config.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"organizations.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/organizations/organizations.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAAoD,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAW/H,oBAAY,gCAAgC;IAC1C,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAQD,KAAK,0BAA0B,GAC3B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAKjC,eAAO,MAAM,uDAAuD,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;wCAuMpH,CAAC"}
+{"version":3,"file":"organizations.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/organizations/organizations.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAAoD,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAW/H;;;;;;;;;;;;;;GAcG;AACH,oBAAY,iCAAiC;IAC3C,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB;;;;;;;OAOG;IACH,gBAAgB,qBAAqB;IACrC;;;;;;OAMG;IACH,OAAO,YAAY;CACpB;AAQD,KAAK,0BAA0B,GAC3B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAKjC,eAAO,MAAM,uDAAuD,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;kBAwoBpH,CAAC"}