@rockcarver/frodo-lib 4.10.0 → 4.11.0-1

package/types/ops/ManagedObjectSchemaOps.d.ts

@@ -0,0 +1,757 @@
+import { type IdObjectSkeletonInterface } from '../api/ApiTypes';
+import { type ManagedObjectSchema, type ManagedObjectSchemaProperty } from '../api/ManagedObjectApi';
+import { State } from '../shared/State';
+/**
+ * A managed-object type's **schema** is its resolved property/relationship
+ * definitions, readable in full via `readManagedObjectSchema` below — a
+ * read-only projection of the same underlying configuration
+ * `IdmConfigOps.ts`'s `readSubConfigEntity('managed', type)` /
+ * `importSubConfigEntity('managed', ...)` read and write as a whole
+ * document. See `ManagedObjectOps.ts`'s own header comment for how schema
+ * relates to managed-object *records* and *configuration*, the other two
+ * things this domain covers.
+ *
+ * Neither path is available on classic (AM-only) deployments at all — there
+ * is no IDM instance there, so neither the dedicated v2 API nor the generic
+ * config path below has anything to talk to. Both require a deployment that
+ * actually runs IDM (Cloud or ForgeOps); see
+ * {@link assertIdmDeploymentForSchemaPropertyApi}.
+ *
+ * There are two ways to *mutate* a type's schema on a deployment that does
+ * run IDM, and they are not interchangeable:
+ * 1. `readManagedObjectSchemaProperty` / `updateManagedObjectSchemaProperty` /
+ *    `removeManagedObjectSchemaProperty` below use IDM's dedicated v2 schema
+ *    API, which is specifically for **relationship-property definitions**,
+ *    one at a time, in place, with no whole-blob read-modify-write. This is
+ *    a standard IDM REST API, introduced in **IDM 7.5.0** (confirmed
+ *    directly in IDM 7.5.0's own "New features" release notes, which link
+ *    to this same endpoint) and present unchanged through IDM 8.1 — not
+ *    Cloud-only, contrary to an earlier version of this comment, which
+ *    wrongly assumed the API was Cloud-specific. Confirmed by directly
+ *    comparing Ping's self-hosted PingIDM REST API reference (7.5 and 8.1)
+ *    against the PingOne Advanced Identity Cloud REST API reference:
+ *    identical endpoint (`/openidm/schema/managed/{type}/
+ *    properties/{propertyName}`), identical `Accept-API-Version: resource=2.0`
+ *    header, identical field shape (including `reverseProperty`), and no
+ *    deployment restriction stated on either side. So this path specifically
+ *    requires IDM 7.5+ (Cloud always qualifies; a ForgeOps deployment on an
+ *    older IDM version would not, though Frodo has no way to detect that and
+ *    doesn't attempt to — the deployment-type gate alone can't distinguish
+ *    IDM versions within ForgeOps). See
+ *    [rockcarver/frodo-lib#388](https://github.com/rockcarver/frodo-lib/issues/388)
+ *    for the original feature request (which itself doesn't claim Cloud-only
+ *    either).
+ * 2. For every other case — any non-relationship property, relationship
+ *    properties on an IDM version that predates 7.5, and whole-type schema
+ *    changes — use `IdmConfigOps.ts`'s `readSubConfigEntity('managed', type)`
+ *    / `importSubConfigEntity('managed', ...)` to read-modify-write the
+ *    entire type definition (edit `.schema.properties` on the object you
+ *    read before writing it back). This is the general-purpose path,
+ *    available on any IDM version; #1 above is an optimization for one
+ *    particular case on a sufficiently recent one, not the default.
+ *
+ * Neither path touches the underlying repository's index/persistence-layer
+ * definitions (e.g. DS's `repo.ds` on ForgeOps) — Frodo has no support for
+ * reading or writing `repo.ds` today, so adding a genuinely new custom
+ * relationship property on ForgeOps still requires a manual, Frodo-unassisted
+ * edit to that file outside either API above.
+ */
+export type ManagedObjectSchemaOps = {
+    /**
+     * Read managed object schema
+     * @param {string} type managed object type, e.g. alpha_user or user
+     * @param {boolean} refreshCache whether to refresh the schema cache for the specified type
+     * @param {ManagedObjectSchemaOptions} options options to filter the returned schema
+     * @returns {Promise<ManagedObjectSchema>} a promise that resolves to a managed object schema
+     */
+    readManagedObjectSchema(type: string, refreshCache?: boolean, options?: ManagedObjectSchemaOptions): Promise<ManagedObjectSchema>;
+    /**
+     * Read a single managed object relationship-property definition. Requires
+     * IDM 7.5+ (Cloud always qualifies) — uses IDM's dedicated v2
+     * relationship-schema API to read one relationship-property definition
+     * without fetching the type's entire schema. For any non-relationship
+     * property, or on an IDM version that predates 7.5, use
+     * readSubConfigEntity('managed', type) and read the property off the
+     * returned schema.properties instead. Neither path is reachable on
+     * classic (AM-only, no IDM at all).
+     * @param {string} type managed object type, e.g. alpha_user or user
+     * @param {string} propertyName schema property name, e.g. custom_merchantId
+     * @returns {Promise<ManagedObjectSchemaProperty>} a promise that resolves to the property definition
+     */
+    readManagedObjectSchemaProperty(type: string, propertyName: string): Promise<ManagedObjectSchemaProperty>;
+    /**
+     * Create or update a single managed object relationship-property
+     * definition, leaving the rest of the type's schema untouched. Requires
+     * IDM 7.5+ — see {@link readManagedObjectSchemaProperty}. For any
+     * non-relationship property, or on an IDM version that predates 7.5, use
+     * importSubConfigEntity('managed', ...) with the full updated type
+     * definition instead. Neither path is reachable on classic.
+     * @param {string} type managed object type, e.g. alpha_user or user
+     * @param {string} propertyName schema property name, e.g. custom_merchantId
+     * @param {ManagedObjectSchemaProperty} propertyData the property definition to write
+     * @returns {Promise<ManagedObjectSchemaProperty>} a promise that resolves to the written property definition
+     */
+    updateManagedObjectSchemaProperty(type: string, propertyName: string, propertyData: ManagedObjectSchemaProperty): Promise<ManagedObjectSchemaProperty>;
+    /**
+     * Remove a single managed object relationship-property definition, leaving
+     * the rest of the type's schema untouched. Requires IDM 7.5+ — see
+     * {@link readManagedObjectSchemaProperty}.
+     * @param {string} type managed object type, e.g. alpha_user or user
+     * @param {string} propertyName schema property name, e.g. custom_merchantId
+     * @returns {Promise<ManagedObjectSchemaProperty>} a promise that resolves to the removed property definition
+     */
+    removeManagedObjectSchemaProperty(type: string, propertyName: string): Promise<ManagedObjectSchemaProperty>;
+    /**
+     * Create a flat (non-relationship) schema property on a managed object
+     * type -- or, with `subProperty`, nested inside an existing `type: object`
+     * property, as a dot-path relative to `propertyName`. Available on any
+     * deployment that runs IDM (Cloud and ForgeOps) -- unlike
+     * {@link updateManagedObjectSchemaProperty}, this goes through the generic
+     * `readSubConfigEntity`/`importSubConfigEntity` whole-type path, not the
+     * dedicated (relationship-only) v2 schema API, so it has no IDM 7.5+
+     * requirement. Refuses (throws `FrodoError`) if the property already
+     * exists at that path -- use
+     * {@link ManagedObjectSchemaOps.updateManagedObjectSchemaFlatProperty}
+     * instead.
+     * @param {string} type managed object type, e.g. alpha_user or user
+     * @param {string} propertyName schema property name, e.g. custom_merchantId
+     * @param {ManagedObjectSchemaPropertyFields} fields the property's field values
+     * @param {string} [subProperty] dot-path to nest the new property under an existing object property beneath propertyName, e.g. "address.street"
+     * @returns {Promise<Record<string, unknown>>} a promise that resolves to the written property definition
+     */
+    createManagedObjectSchemaFlatProperty(type: string, propertyName: string, fields: ManagedObjectSchemaPropertyFields, subProperty?: string): Promise<Record<string, unknown>>;
+    /**
+     * Update an existing flat (non-relationship) schema property on a managed
+     * object type -- or, with `subProperty`, a nested property reached via
+     * that dot-path. Only the fields present in `changedFields` change;
+     * everything else keeps its current value. See
+     * {@link ManagedObjectSchemaOps.createManagedObjectSchemaFlatProperty} for
+     * the deployment/API-path notes. Refuses (throws `FrodoError`) if the
+     * property doesn't exist at that path -- use
+     * {@link ManagedObjectSchemaOps.createManagedObjectSchemaFlatProperty}
+     * instead.
+     * @param {string} type managed object type, e.g. alpha_user or user
+     * @param {string} propertyName schema property name, e.g. custom_merchantId
+     * @param {Partial<ManagedObjectSchemaPropertyFields>} changedFields only the field overrides to apply
+     * @param {string} [subProperty] dot-path to a nested property beneath propertyName, e.g. "address.street"
+     * @returns {Promise<{ current: Record<string, unknown>; propertyData: Record<string, unknown> }>} a promise that resolves to the property's prior and newly-written definitions
+     */
+    updateManagedObjectSchemaFlatProperty(type: string, propertyName: string, changedFields: Partial<ManagedObjectSchemaPropertyFields>, subProperty?: string): Promise<{
+        current: Record<string, unknown>;
+        propertyData: Record<string, unknown>;
+    }>;
+    /**
+     * Remove a flat (non-relationship) schema property from a managed object
+     * type -- or, with `subProperty`, a nested property reached via that
+     * dot-path. See
+     * {@link ManagedObjectSchemaOps.createManagedObjectSchemaFlatProperty} for
+     * the deployment/API-path notes. Refuses (throws `FrodoError`) if the
+     * property doesn't exist at that path.
+     * @param {string} type managed object type, e.g. alpha_user or user
+     * @param {string} propertyName schema property name, e.g. custom_merchantId
+     * @param {string} [subProperty] dot-path to a nested property beneath propertyName, e.g. "address.street"
+     * @returns {Promise<Record<string, unknown>>} a promise that resolves to the removed property definition
+     */
+    removeManagedObjectSchemaFlatProperty(type: string, propertyName: string, subProperty?: string): Promise<Record<string, unknown>>;
+    /**
+     * Create a new managed object type. Refuses (throws `FrodoError`) if a
+     * type with that name already exists -- use
+     * {@link ManagedObjectSchemaOps.updateManagedObjectType} instead. Seeds a
+     * minimal schema (just the `_id` property, a populated `order` array, and
+     * a default icon if `fields.icon` isn't given); custom properties/
+     * relationships are added afterward via the flat-property/relationship-
+     * property paths, which already keep `order`/`required` in sync as they
+     * go.
+     * @param {string} type managed object type, e.g. alpha_widget
+     * @param {ManagedObjectTypeFields} fields the new type's field values (title required)
+     * @returns {Promise<Record<string, unknown>>} a promise that resolves to the written type schema
+     */
+    createManagedObjectType(type: string, fields: ManagedObjectTypeFields): Promise<Record<string, unknown>>;
+    /**
+     * Update an existing managed object type's own metadata (title/icon/
+     * description). Only the fields present in `changedFields` change;
+     * everything else keeps its current value. Refuses (throws `FrodoError`)
+     * if the type doesn't exist -- use
+     * {@link ManagedObjectSchemaOps.createManagedObjectType} instead.
+     * @param {string} type managed object type, e.g. alpha_widget
+     * @param {Partial<ManagedObjectTypeFields>} changedFields only the field overrides to apply
+     * @returns {Promise<{ current: ManagedObjectTypeFields; proposed: ManagedObjectTypeFields }>} a promise that resolves to the type's prior and newly-written metadata
+     */
+    updateManagedObjectType(type: string, changedFields: Partial<ManagedObjectTypeFields>): Promise<{
+        current: ManagedObjectTypeFields;
+        proposed: ManagedObjectTypeFields;
+    }>;
+    /**
+     * Remove a managed object type's entire definition (schema included). No
+     * separate existence pre-check -- the underlying config write already
+     * throws its own not-found error if the type is missing, so a second read
+     * here would be a redundant round trip.
+     * @param {string} type managed object type, e.g. alpha_widget
+     * @returns {Promise<void>} a promise that resolves when the type has been removed
+     */
+    removeManagedObjectType(type: string): Promise<void>;
+    /**
+     * Create a new relationship schema property, via IDM's dedicated v2
+     * schema API (requires IDM 7.5+; Cloud always qualifies). Refuses
+     * (throws `FrodoError`) if a property with that name already exists --
+     * use {@link ManagedObjectSchemaOps.updateManagedObjectSchemaRelationshipProperty}
+     * instead. When `reverse` is given, the reverse side on
+     * `fields.targetObject` is auto-created by the server in the same write.
+     * @param {string} type managed object type, e.g. alpha_aiagentprivilege
+     * @param {string} propertyName relationship property name, e.g. agent
+     * @param {ManagedObjectSchemaRelationshipPropertyFields} fields the forward side's field values
+     * @param {ManagedObjectSchemaRelationshipReverseFields} [reverse] the reverse side's field values, if creating both sides
+     * @returns {Promise<Record<string, unknown>>} a promise that resolves to the written forward-side definition
+     */
+    createManagedObjectSchemaRelationshipProperty(type: string, propertyName: string, fields: ManagedObjectSchemaRelationshipPropertyFields, reverse?: ManagedObjectSchemaRelationshipReverseFields): Promise<Record<string, unknown>>;
+    /**
+     * Update an existing relationship schema property, via IDM's dedicated
+     * v2 schema API. Refuses (throws `FrodoError`) if the property doesn't
+     * exist -- use
+     * {@link ManagedObjectSchemaOps.createManagedObjectSchemaRelationshipProperty}
+     * instead. Only the fields present in `changedFields` change; everything
+     * else keeps its current value. A configured reverse side's descriptor is
+     * always re-supplied (required by the v2 API on every write of a
+     * bidirectional property), regardless of `withReverse`; `withReverse`
+     * additionally applies `changedFields`' overrides to the reverse side
+     * itself and writes it as a second, separate call -- if that second call
+     * fails after the forward write already succeeded, the thrown error says
+     * so explicitly; there is no automatic rollback.
+     * @param {string} type managed object type, e.g. alpha_aiagentprivilege
+     * @param {string} propertyName relationship property name, e.g. agent
+     * @param {Partial<ManagedObjectSchemaRelationshipPropertyFields>} changedFields only the field overrides to apply
+     * @param {boolean} [withReverse] true to also update the inferred reverse side
+     * @returns {Promise<{ forward: Record<string, unknown>; reverse?: { type: string; propertyName: string; propertyData: Record<string, unknown> } }>} a promise that resolves to the written definition(s)
+     */
+    updateManagedObjectSchemaRelationshipProperty(type: string, propertyName: string, changedFields: Partial<ManagedObjectSchemaRelationshipPropertyFields>, withReverse?: boolean): Promise<{
+        forward: Record<string, unknown>;
+        reverse?: {
+            type: string;
+            propertyName: string;
+            propertyData: Record<string, unknown>;
+        };
+    }>;
+    /**
+     * Remove a relationship schema property, via IDM's dedicated v2 schema
+     * API. `withReverse` infers the reverse side from the forward property's
+     * own current definition and deletes it first, then the forward side.
+     * Deleting the reverse side of a bidirectionally-auto-created pair
+     * cascades and removes the forward side too, confirmed live -- a 404 on
+     * the forward-side delete immediately after a `withReverse` reverse-side
+     * delete means the desired end state (both sides gone) was already
+     * reached, and is treated as success, not surfaced as an error.
+     * @param {string} type managed object type, e.g. alpha_aiagentprivilege
+     * @param {string} propertyName relationship property name, e.g. agent
+     * @param {boolean} [withReverse] true to also delete the inferred reverse side
+     * @returns {Promise<{ current: Record<string, unknown>; reverse?: { type: string; propertyName: string; current: Record<string, unknown> } }>} a promise that resolves to the removed definition(s)
+     */
+    removeManagedObjectSchemaRelationshipProperty(type: string, propertyName: string, withReverse?: boolean): Promise<{
+        current: Record<string, unknown>;
+        reverse?: {
+            type: string;
+            propertyName: string;
+            current: Record<string, unknown>;
+        };
+    }>;
+    /**
+     * Read a single relationship schema property, returning `null` (rather
+     * than throwing) if it doesn't exist. A confirmed 404 from the dedicated
+     * v2 API reliably means the property itself doesn't exist; any other
+     * failure propagates rather than being silently treated as "not found".
+     * @param {string} type managed object type, e.g. alpha_aiagentprivilege
+     * @param {string} propertyName relationship property name, e.g. agent
+     * @returns {Promise<Record<string, unknown> | null>} a promise that resolves to the property definition, or null if not found
+     */
+    readManagedObjectSchemaRelationshipPropertyOrNull(type: string, propertyName: string): Promise<Record<string, unknown> | null>;
+};
+declare const _default: (state: State) => ManagedObjectSchemaOps;
+export default _default;
+export type ManagedObjectSchemaOptions = {
+    /**
+     * Whether to exclude virtual properties from the returned schema.
+     * Virtual properties are non-persisted properties that are calculated
+     * or derived at runtime.
+     * */
+    excludeVirtual?: boolean;
+    /**
+     * Whether to exclude relationship properties from the returned schema.
+     */
+    excludeRelationships?: boolean;
+    /**
+     * If specified, only relationship properties whose resourceCollection
+     * path matches any of the values in this array will be included in the
+     * returned schema when excludeRelationships is true. This option is
+     * ignored if excludeRelationships is false.
+     */
+    includeRelationshipsFilter?: string[];
+};
+export declare function readManagedObjectSchema({ type, refreshCache, options, state, }: {
+    type: string;
+    refreshCache?: boolean;
+    options?: ManagedObjectSchemaOptions;
+    state: State;
+}): Promise<ManagedObjectSchema>;
+/**
+ * Read a single managed object relationship-property definition. Available
+ * on any deployment that runs IDM (Cloud and ForgeOps) — see
+ * {@link assertIdmDeploymentForSchemaPropertyApi}.
+ */
+export declare function readManagedObjectSchemaProperty({ type, propertyName, state, }: {
+    type: string;
+    propertyName: string;
+    state: State;
+}): Promise<ManagedObjectSchemaProperty>;
+/**
+ * Create or update a single managed object relationship-property
+ * definition, leaving the rest of the type's schema untouched. Available
+ * on any deployment that runs IDM (Cloud and ForgeOps) — see
+ * {@link assertIdmDeploymentForSchemaPropertyApi}. Invalidates
+ * (rather than eagerly re-fetching) the cached whole-type schema
+ * readManagedObjectSchema uses, so the next read for this type picks up the
+ * change without an extra round-trip here.
+ * @param {boolean} wait wait for the config change to fully propagate before returning. Defaults to true — see {@link putManagedObjectSchemaProperty}.
+ */
+export declare function updateManagedObjectSchemaProperty({ type, propertyName, propertyData, wait, state, }: {
+    type: string;
+    propertyName: string;
+    propertyData: ManagedObjectSchemaProperty;
+    wait?: boolean;
+    state: State;
+}): Promise<ManagedObjectSchemaProperty>;
+/**
+ * Remove a single managed object relationship-property definition, leaving
+ * the rest of the type's schema untouched. Available on any deployment that
+ * runs IDM (Cloud and ForgeOps) — see
+ * {@link assertIdmDeploymentForSchemaPropertyApi}. Invalidates the cached
+ * whole-type schema; see {@link updateManagedObjectSchemaProperty}.
+ * @param {boolean} wait wait for the config change to fully propagate before returning. Defaults to true — see {@link putManagedObjectSchemaProperty}.
+ */
+export declare function removeManagedObjectSchemaProperty({ type, propertyName, wait, state, }: {
+    type: string;
+    propertyName: string;
+    wait?: boolean;
+    state: State;
+}): Promise<ManagedObjectSchemaProperty>;
+/**
+ * ---------------------------------------------------------------------
+ * Flat (non-relationship) schema property support.
+ * ---------------------------------------------------------------------
+ * Everything below this point supports `createManagedObjectSchemaFlatProperty`
+ * / `updateManagedObjectSchemaFlatProperty` /
+ * `removeManagedObjectSchemaFlatProperty` — the generic, always-available
+ * (path 2 in this file's module header) read-modify-write of a single flat
+ * property definition, via `readSubConfigEntity`/`importSubConfigEntity`.
+ * Unlike the dedicated v2 relationship-property API above, this path has no
+ * IDM-version requirement and is not limited to relationship properties, but
+ * it is also not atomic against a concurrent writer of the same type — the
+ * same tradeoff `readSubConfigEntity`/`importSubConfigEntity` always carry.
+ */
+type ManagedObjectTypeConfig = IdObjectSkeletonInterface & {
+    name: string;
+    schema?: ManagedObjectSchema;
+};
+/** A schema property container: a managed-object type's own schema, or a nested `type: object` property's own sub-schema — both shapes carry the same `properties`/`order`/`required` triad. */
+export type PropertyContainer = {
+    properties?: Record<string, Record<string, unknown>>;
+    order?: string[];
+    required?: string[];
+};
+/**
+ * Sets or replaces a schema property definition within a property container
+ * (a managed-object type's own schema, or — via a sub-property path — a
+ * nested `type: object` property's own sub-schema), keeping that container's
+ * own order/required arrays in sync.
+ */
+export declare function setSchemaProperty(container: PropertyContainer, propertyName: string, propertyData: Record<string, unknown>): void;
+/**
+ * Removes a schema property definition (and its required/order bookkeeping)
+ * from a property container — see {@link setSchemaProperty}.
+ */
+export declare function removeSchemaProperty(container: PropertyContainer, propertyName: string): void;
+/** Splits a sub-property dot-path (e.g. `"address.geo.lat"`) into segments; `undefined`/empty yields no segments. */
+export declare function parseSubPropertyPath(subProperty?: string): string[];
+/**
+ * Walks a property path (e.g. `["profile", "address"]`) starting from the
+ * type's own schema, down through `type: object` (or array-of-object)
+ * properties, requiring every segment to already exist and be `type:
+ * object`. Returns the resulting container — itself a valid target for
+ * `setSchemaProperty`/`removeSchemaProperty`/further navigation, since a
+ * nested object property's own body has the same
+ * `properties`/`order`/`required` shape as the type's top-level schema.
+ */
+export declare function navigateToPropertyContainer(schema: PropertyContainer, path: string[]): PropertyContainer;
+/**
+ * Walks a property path (e.g. `["profile", "address", "street"]`, where
+ * `"profile"` is the top-level property name and `["address", "street"]`
+ * came from a sub-property path) down to its leaf. Every segment except the
+ * last must already exist and be `type: object`. Returns the immediate
+ * parent container (whose `.properties`/`.order`/`.required` the caller
+ * reads/writes) and the leaf property name, so the same read/write logic
+ * works identically whether the target is top-level or nested.
+ */
+export declare function navigatePropertyPath(schema: PropertyContainer, path: string[]): {
+    container: PropertyContainer;
+    propertyName: string;
+};
+/**
+ * Every schema property type the Admin UI's own property-type picker offers
+ * (confirmed live against a hand-built managed-object type). Single source
+ * of truth feeding both frodo-cli's `--property-type` CLI `.choices()`/help
+ * text and this module's own {@link buildManagedObjectSchemaPropertyPayload}
+ * validation: add a type here once IDM's picker offers it, and every
+ * consumer picks it up automatically, instead of drifting out of sync as
+ * separately-maintained lists.
+ */
+export declare const MANAGED_OBJECT_SCHEMA_CREATABLE_PROPERTY_TYPES: readonly ["string", "number", "boolean", "date", "time", "datetime", "duration", "object"];
+export type ManagedObjectSchemaCreatablePropertyType = (typeof MANAGED_OBJECT_SCHEMA_CREATABLE_PROPERTY_TYPES)[number];
+/**
+ * Field values for a flat (non-relationship) schema property. Used both for
+ * create (fully specified) and update (only the explicitly-changed subset,
+ * merged onto the property's current definition via
+ * {@link extractManagedObjectSchemaPropertyFields}).
+ */
+export type ManagedObjectSchemaPropertyFields = {
+    type?: ManagedObjectSchemaCreatablePropertyType;
+    array?: boolean;
+    title?: string;
+    description?: string;
+    required?: boolean;
+    searchable?: boolean;
+    userEditable?: boolean;
+    notViewable?: boolean;
+    returnByDefault?: boolean;
+    defaultValue?: unknown;
+    enumValues?: string[];
+    enumTitles?: string[];
+    /** JS source (already read from the file a caller's --on-retrieve-script points at), not a file path. */
+    onRetrieveScript?: string;
+    /** JS source (already read from the file a caller's --on-store-script points at), not a file path. */
+    onStoreScript?: string;
+    /** Relationship property name(s) this RDVP derives its value through — IDM's `queryConfig.referencedRelationshipFields`. */
+    deriveFromRelationship?: string[];
+    /** Fields to pull from each referenced object — IDM's `queryConfig.referencedObjectFields`. */
+    deriveFields?: string[];
+    flatten?: boolean;
+};
+/**
+ * Assembles a schema-property payload (a leaf type, or an array of that
+ * type) from resolved field values, validating `type` and the
+ * `enumValues`/`enumTitles` pairing along the way (throws `FrodoError`).
+ * `date`/`time`/`datetime`/`duration` are all `type: "string"` with a
+ * `format` field under the hood — confirmed against a type created via the
+ * Admin UI's own property-type picker (which offers exactly these four
+ * alongside String/Number/Boolean/Object), including the exact `format`
+ * values (`"date"`, `"time"`, `"datetime"` — not the more common
+ * `"date-time"` — and `"duration"`). `object` is always written as a bare
+ * `{ type: "object" }` with no `properties`/`order`, matching a live example
+ * of an empty object property — a *structured* object property (its own
+ * nested set of sub-properties) is a deliberate scope choice, not a
+ * technical limitation of the property itself: these fields only cover a
+ * flat property definition, so a structured object needs a verbatim
+ * `readSubConfigEntity`/`importSubConfigEntity` round trip instead, which
+ * writes the definition as-is and has no such restriction.
+ *
+ * `default`/`enum`/`enumTitles` sit on the leaf type node (so they land on
+ * `items` for an array property, constraining each element) — confirmed
+ * against a live `enum` property. `isVirtual`/`onRetrieve`/`onStore`/
+ * `queryConfig` sit at the top level instead, confirmed against two live
+ * managed-object examples: a pure RDVP (relationship-derived virtual
+ * property, `queryConfig` only, no script), and a script-derived virtual
+ * property (`onRetrieve` only, no `queryConfig`) — both live entirely inside
+ * `schema.properties`, the same place create/update already read and write,
+ * so no new API surface was needed for either.
+ *
+ * Note on the `type` validation below: it runs against whatever ends up in
+ * `fields.type`, including a value merely carried through unchanged from an
+ * existing property's current definition during an update (see
+ * {@link extractManagedObjectSchemaPropertyFields}) — so updating so much as
+ * the title of a property whose type isn't one of
+ * {@link MANAGED_OBJECT_SCHEMA_CREATABLE_PROPERTY_TYPES} (e.g. one
+ * hand-crafted outside this flat-property path) fails here too. That's a
+ * deliberate tradeoff for a single, consistently-enforced source of truth
+ * rather than validating only caller-supplied overrides; a property in that
+ * situation still has the unrestricted `readSubConfigEntity`/
+ * `importSubConfigEntity` verbatim round trip available as an escape hatch.
+ */
+export declare function buildManagedObjectSchemaPropertyPayload(propertyName: string, fields: ManagedObjectSchemaPropertyFields): Record<string, unknown>;
+/**
+ * Reverse-parses a live schema property definition back into
+ * {@link ManagedObjectSchemaPropertyFields}, so update can merge only the
+ * explicitly-changed overrides onto the property's actual current state
+ * rather than create-time defaults.
+ */
+export declare function extractManagedObjectSchemaPropertyFields(current: Record<string, unknown>): ManagedObjectSchemaPropertyFields;
+/**
+ * Create a flat (non-relationship) schema property. See
+ * {@link ManagedObjectSchemaOps.createManagedObjectSchemaFlatProperty} for
+ * the full doc comment.
+ */
+export declare function createManagedObjectSchemaFlatProperty({ type, propertyName, fields, subProperty, state, }: {
+    type: string;
+    propertyName: string;
+    fields: ManagedObjectSchemaPropertyFields;
+    subProperty?: string;
+    state: State;
+}): Promise<Record<string, unknown>>;
+/**
+ * Update a flat (non-relationship) schema property. See
+ * {@link ManagedObjectSchemaOps.updateManagedObjectSchemaFlatProperty} for
+ * the full doc comment.
+ */
+export declare function updateManagedObjectSchemaFlatProperty({ type, propertyName, changedFields, subProperty, state, }: {
+    type: string;
+    propertyName: string;
+    changedFields: Partial<ManagedObjectSchemaPropertyFields>;
+    subProperty?: string;
+    state: State;
+}): Promise<{
+    current: Record<string, unknown>;
+    propertyData: Record<string, unknown>;
+}>;
+/**
+ * Remove a flat (non-relationship) schema property. See
+ * {@link ManagedObjectSchemaOps.removeManagedObjectSchemaFlatProperty} for
+ * the full doc comment.
+ */
+export declare function removeManagedObjectSchemaFlatProperty({ type, propertyName, subProperty, state, }: {
+    type: string;
+    propertyName: string;
+    subProperty?: string;
+    state: State;
+}): Promise<Record<string, unknown>>;
+/**
+ * ---------------------------------------------------------------------
+ * Managed-object type-level create/update/remove support.
+ * ---------------------------------------------------------------------
+ * Everything below this point supports `createManagedObjectType` /
+ * `updateManagedObjectType` / `removeManagedObjectType` -- creating,
+ * renaming/re-iconing/re-describing, and removing a managed-object type's
+ * own definition (as opposed to one of its schema properties, above). Uses
+ * the same `readSubConfigEntity`/`importSubConfigEntity`/
+ * `removeSubConfigEntity` path as the flat-property functions, since a
+ * type's own metadata (title/icon/description) lives on the same
+ * `schema` object as its `properties`.
+ */
+/**
+ * Default icon written for a new managed-object type when `fields.icon`
+ * isn't given. A Material Design Icon name (not a Font Awesome name) --
+ * confirmed via PingIDM's docs that `icon` only applies to standalone IDM,
+ * while `mat-icon` is what the Ping Identity Platform's own Admin UI reads,
+ * and managed-object type create/update only ever target Cloud/ForgeOps
+ * (Platform deployments), never standalone IDM.
+ */
+export declare const MANAGED_OBJECT_TYPE_DEFAULT_ICON = "widgets";
+/**
+ * A managed-object type's own metadata, as resolved from caller-supplied
+ * field values. Used both for create (title required) and update (only the
+ * explicitly-changed subset, merged onto the type's current definition).
+ */
+export type ManagedObjectTypeFields = {
+    title?: string;
+    icon?: string;
+    description?: string;
+};
+/**
+ * Assembles a minimal managed-object type definition from resolved field
+ * values -- just the type's own identity/metadata, no custom properties
+ * (those are added afterward via the flat-property/relationship-property
+ * paths, which already keep `schema.order`/`schema.required` in sync as
+ * they go). Always writes a populated `order` array (`['_id']`) and a
+ * `mat-icon`, even when `fields.icon` isn't given -- a type whose schema
+ * lacks a populated `order` array has been observed to cause the v2
+ * relationship-property API to fail later, so an icon is kept as a paired
+ * default rather than risking that failure mode.
+ *
+ * Cast via `unknown`: the real API doesn't require `resourceCollection` on
+ * the whole-type schema (absent in every real fixture confirmed this
+ * session), even though `ManagedObjectSchema`'s type declares it required;
+ * `mat-icon`/`description` aren't in `ManagedObjectSchema`'s type at all
+ * (frodo-lib only declares `icon`), same reason.
+ */
+export declare function buildManagedObjectTypeSchema(type: string, fields: ManagedObjectTypeFields): ManagedObjectTypeConfig;
+/**
+ * Create a managed object type. See
+ * {@link ManagedObjectSchemaOps.createManagedObjectType} for the full doc
+ * comment.
+ */
+export declare function createManagedObjectType({ type, fields, state, }: {
+    type: string;
+    fields: ManagedObjectTypeFields;
+    state: State;
+}): Promise<Record<string, unknown>>;
+/**
+ * Update a managed object type. See
+ * {@link ManagedObjectSchemaOps.updateManagedObjectType} for the full doc
+ * comment.
+ */
+export declare function updateManagedObjectType({ type, changedFields, state, }: {
+    type: string;
+    changedFields: Partial<ManagedObjectTypeFields>;
+    state: State;
+}): Promise<{
+    current: ManagedObjectTypeFields;
+    proposed: ManagedObjectTypeFields;
+}>;
+/**
+ * Remove a managed object type. See
+ * {@link ManagedObjectSchemaOps.removeManagedObjectType} for the full doc
+ * comment.
+ */
+export declare function removeManagedObjectType({ type, state, }: {
+    type: string;
+    state: State;
+}): Promise<void>;
+/**
+ * ---------------------------------------------------------------------
+ * Relationship-property create/update/remove support.
+ * ---------------------------------------------------------------------
+ * Everything below this point supports
+ * `createManagedObjectSchemaRelationshipProperty` /
+ * `updateManagedObjectSchemaRelationshipProperty` /
+ * `removeManagedObjectSchemaRelationshipProperty` -- unlike the flat-
+ * property and type-level functions above, these go through the dedicated
+ * v2 relationship-schema API (`readManagedObjectSchemaProperty` /
+ * `updateManagedObjectSchemaProperty` / `removeManagedObjectSchemaProperty`,
+ * already defined earlier in this file), not the generic
+ * `readSubConfigEntity`/`importSubConfigEntity` whole-type path -- see this
+ * file's own module header for why. A bidirectional relationship has a
+ * forward and a reverse side, each its own separate property on (usually)
+ * two different managed-object types; creation can auto-create both sides
+ * in one write (the server does this), but update/remove of an existing
+ * bidirectional pair always requires two separate API calls, one per side,
+ * with no cross-call transaction -- the ordering and partial-failure
+ * handling below exists specifically to keep that reality honest rather
+ * than pretending it's atomic.
+ */
+/** Field values for a relationship (or array-of-relationship) schema property, as resolved from caller-supplied values. */
+export type ManagedObjectSchemaRelationshipPropertyFields = {
+    targetObject?: string;
+    many?: boolean;
+    queryFields?: string[];
+    title?: string;
+    description?: string;
+    label?: string;
+    queryFilter?: string;
+    sortKeys?: string[];
+    notify?: boolean;
+    notifySelf?: boolean;
+    searchable?: boolean;
+    userEditable?: boolean;
+    notViewable?: boolean;
+    notValidate?: boolean;
+    returnByDefault?: boolean;
+    reversePropertyName?: string;
+};
+/** Field values for the reverse side of a bidirectional relationship, embedded in the forward side's own write. */
+export type ManagedObjectSchemaRelationshipReverseFields = {
+    propertyName: string;
+    many: boolean;
+    queryFields: string[];
+    title?: string;
+    description?: string;
+};
+/**
+ * Assembles a full relationship (or array-of-relationship) schema-property
+ * payload from resolved field values: `validate`/`viewable` default true,
+ * `userEditable`/`returnByDefault`/`notifySelf`/resourceCollection `notify`
+ * default false, `queryFilter` defaults `'true'`, and `searchable`/
+ * `sortKeys` are omitted entirely unless explicitly given. `reverse`, when
+ * given (create, or update re-supplying an existing bidirectional
+ * property's required descriptor), embeds a reverse-property descriptor --
+ * see {@link buildReversePropertyDescriptor}.
+ *
+ * Built as a plain object and cast at the call site rather than typed as
+ * `ManagedObjectSchemaProperty` throughout: the real IDM v2 API is more
+ * lenient than that type declares (`sortKeys`/`searchable` in particular
+ * are routinely absent from real property definitions returned by the
+ * server).
+ */
+export declare function buildManagedObjectSchemaRelationshipPropertyPayload(propertyName: string, fields: ManagedObjectSchemaRelationshipPropertyFields, reverse?: ManagedObjectSchemaRelationshipReverseFields): Record<string, unknown>;
+/**
+ * Reverse-parses a live relationship (or array-of-relationship) property
+ * definition back into {@link ManagedObjectSchemaRelationshipPropertyFields},
+ * so update can merge only the explicitly-changed overrides onto the
+ * property's actual current state rather than create-time defaults.
+ */
+export declare function extractManagedObjectSchemaRelationshipPropertyFields(current: Record<string, unknown>): ManagedObjectSchemaRelationshipPropertyFields;
+/**
+ * Turns an already-fetched relationship property's extracted fields into
+ * the descriptor shape {@link buildManagedObjectSchemaRelationshipPropertyPayload}'s
+ * `reverse` parameter expects. Used on update: the v2 API requires a
+ * `resourceCollection[0].reverseProperty` descriptor on *every* write of a
+ * property that has `reverseRelationship: true` set, not just its initial
+ * creation -- live-confirmed via a 400 ("field is required") when updating
+ * an already-bidirectional property without one -- so any update to a
+ * property with a configured reverse side must re-supply this descriptor
+ * even when the caller isn't touching the reverse side's own fields.
+ */
+export declare function toManagedObjectSchemaRelationshipReverseFields(propertyName: string, fields: ManagedObjectSchemaRelationshipPropertyFields): ManagedObjectSchemaRelationshipReverseFields;
+/**
+ * Infers a relationship property's reverse side (type + property name) from
+ * its own definition -- the source of truth `withReverse` reads from on
+ * update/remove, needing no separate identity parameters.
+ */
+export declare function inferManagedObjectSchemaRelationshipReverseIdentity(property: Record<string, unknown>): {
+    type: string;
+    propertyName: string;
+} | null;
+/**
+ * Read a relationship schema property. See
+ * {@link ManagedObjectSchemaOps.readManagedObjectSchemaRelationshipPropertyOrNull}
+ * for the full doc comment.
+ */
+export declare function readManagedObjectSchemaRelationshipPropertyOrNull({ type, propertyName, state, }: {
+    type: string;
+    propertyName: string;
+    state: State;
+}): Promise<Record<string, unknown> | null>;
+/**
+ * Create a relationship schema property. See
+ * {@link ManagedObjectSchemaOps.createManagedObjectSchemaRelationshipProperty}
+ * for the full doc comment.
+ */
+export declare function createManagedObjectSchemaRelationshipProperty({ type, propertyName, fields, reverse, state, }: {
+    type: string;
+    propertyName: string;
+    fields: ManagedObjectSchemaRelationshipPropertyFields;
+    reverse?: ManagedObjectSchemaRelationshipReverseFields;
+    state: State;
+}): Promise<Record<string, unknown>>;
+/**
+ * Update a relationship schema property. See
+ * {@link ManagedObjectSchemaOps.updateManagedObjectSchemaRelationshipProperty}
+ * for the full doc comment.
+ */
+export declare function updateManagedObjectSchemaRelationshipProperty({ type, propertyName, changedFields, withReverse, state, }: {
+    type: string;
+    propertyName: string;
+    changedFields: Partial<ManagedObjectSchemaRelationshipPropertyFields>;
+    withReverse?: boolean;
+    state: State;
+}): Promise<{
+    forward: Record<string, unknown>;
+    reverse?: {
+        type: string;
+        propertyName: string;
+        propertyData: Record<string, unknown>;
+    };
+}>;
+/**
+ * Remove a relationship schema property. See
+ * {@link ManagedObjectSchemaOps.removeManagedObjectSchemaRelationshipProperty}
+ * for the full doc comment.
+ */
+export declare function removeManagedObjectSchemaRelationshipProperty({ type, propertyName, withReverse, state, }: {
+    type: string;
+    propertyName: string;
+    withReverse?: boolean;
+    state: State;
+}): Promise<{
+    current: Record<string, unknown>;
+    reverse?: {
+        type: string;
+        propertyName: string;
+        current: Record<string, unknown>;
+    };
+}>;
+//# sourceMappingURL=ManagedObjectSchemaOps.d.ts.map