@kernelminds/scailo-sdk 0.1.28 → 0.1.30

package/lib/esm/src/families.scailo_connect.js

@@ -29,7 +29,19 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Create and save as draft
+         * Saves a new record as a draft without triggering side effects.
+         *
+         * Use this method when you have incomplete information but wish to persist
+         * the record for later completion. The record remains in a `DRAFT` state.
+         *
+         * **Note:** Some strict validation rules may be relaxed in the backend for drafts compared to `Create`.
+         *
+         * **Side Effects:**
+         * - Generates a unique system UUID.
+         * - Records an audit log for the "Draft" action.
+         *
+         * **Errors:**
+         * - `INVALID_ARGUMENT`: If critical system fields are missing.
          *
          * @generated from rpc Scailo.FamiliesService.Draft
          */
@@ -40,7 +52,13 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Update draft
+         * Updates an existing record that is currently in `DRAFT` status.
+         *
+         * This method allows modification of all primary attributes while the record is not yet verified.
+         *
+         * **Errors:**
+         * - `FAILED_PRECONDITION`: If the record is not in a `DRAFT` state.
+         * - `NOT_FOUND`: If the provided ID does not exist.
          *
          * @generated from rpc Scailo.FamiliesService.DraftUpdate
          */
@@ -51,7 +69,37 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Send for verification
+         * Code Generation Logic:
+         * If `parent_id` > 0, the system automatically prefixes the parent family's
+         * code to the provided `code` before persistence (e.g., "PARENT_CODE.SUB_CODE").
+         *
+         * Preconditions:
+         * - The family must be in `DRAFT` or `REVISION` state.
+         * - The family `amendment_count` must be 0 (never previously approved).
+         *
+         * Errors:
+         * - `FAILED_PRECONDITION`: If the family has been approved previously (amendment_count > 0).
+         * - `INVALID_ARGUMENT`: If the hierarchy (parent_id/is_leaf) is self-referential or cyclic.
+         * - `NOT_FOUND`: If the Family ID or the specified `parent_id` does not exist.
+         *
+         * @generated from rpc Scailo.FamiliesService.UpdateIdentity
+         */
+        updateIdentity: {
+            name: "UpdateIdentity",
+            I: families_scailo_pb_js_1.FamiliesServiceUpdateIdentityRequest,
+            O: base_scailo_pb_js_1.IdentifierResponse,
+            kind: protobuf_1.MethodKind.Unary,
+        },
+        /**
+         * Submits a record in `DRAFT` or `REVISION` status for verification.
+         *
+         * This triggers the first stage of the approval workflow.
+         *
+         * **Status Transition:** -> `PREVERIFY`
+         *
+         * **Side Effects:**
+         * - Notifies designated verifiers or approvers.
+         * - Locks certain fields from being updated without returning to `REVISION`.
          *
          * @generated from rpc Scailo.FamiliesService.SendForVerification
          */
@@ -62,7 +110,12 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Verify
+         * Marks a record as verified, signaling that it is ready for final approval.
+         *
+         * **Status Transition:** -> `VERIFIED`
+         *
+         * **Side Effects:**
+         * - Records the verifying user and timestamp in the audit logs.
          *
          * @generated from rpc Scailo.FamiliesService.Verify
          */
@@ -73,7 +126,13 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Approve
+         * Officially approves the record.
+         *
+         * **Status Transition:** -> `STANDING`
+         *
+         * **Side Effects:**
+         * - Finalizes the `final_ref_number`.
+         * - Records the approver's identity and timestamp.
          *
          * @generated from rpc Scailo.FamiliesService.Approve
          */
@@ -84,7 +143,14 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Send For Revision
+         * Sends the record back to the creator for corrections.
+         *
+         * Use this if details are incorrect or supporting documents (in the vault) are missing.
+         *
+         * **Status Transition:** -> `REVISION`
+         *
+         * **Side Effects:**
+         * - Notifies the record creator that changes are required.
          *
          * @generated from rpc Scailo.FamiliesService.SendForRevision
          */
@@ -95,7 +161,10 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Update revision
+         * Updates a record that has been sent back for `REVISION`.
+         *
+         * **Side Effects:**
+         * - Re-validates the updated fields.
          *
          * @generated from rpc Scailo.FamiliesService.RevisionUpdate
          */
@@ -106,7 +175,9 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Halt
+         * Temporarily halts processing of the record.
+         *
+         * **Status Transition:** -> `HALTED`
          *
          * @generated from rpc Scailo.FamiliesService.Halt
          */
@@ -117,7 +188,11 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Discard
+         * Permanently cancels the record.
+         *
+         * Records in this state are typically ignored.
+         *
+         * **Status Transition:** -> `DISCARDED`
          *
          * @generated from rpc Scailo.FamiliesService.Discard
          */
@@ -128,7 +203,10 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Restore
+         * Restores a previously `DISCARDED` or `HALTED` record.
+         *
+         * **Side Effects:**
+         * - Moves the record back to `PREVERIFY` and sends for verification.
          *
          * @generated from rpc Scailo.FamiliesService.Restore
          */
@@ -139,7 +217,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Add comment
+         * Adds an audit comment to the record's history without changing its current lifecycle status.
          *
          * Send Email
          * rpc SendEmail (Identifier) returns (IdentifierResponse);
@@ -220,7 +298,13 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Import families using a CSV file (duplicate codes will be skipped)
+         * Bulk imports records from a provided CSV file.
+         * Behavior:
+         * - Deduplication: Skips entries where the `code` already exists in the system.
+         * - Atomicity: This is an "all-or-nothing" operation; if any part of the
+         *   import fails, no changes are committed.
+         * - Idempotency: Multiple calls with the same CSV result in the same state.
+         * Returns a list of UUIDs for all successfully processed or existing records.
          *
          * @generated from rpc Scailo.FamiliesService.ImportFromCSV
          */
@@ -550,7 +634,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * View by ID
+         * Retrieves a single record by its internal numeric ID. This operation is optimized for high-performance internal system logic and backend-to-backend communication
          *
          * @generated from rpc Scailo.FamiliesService.ViewByID
          */
@@ -561,7 +645,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * View by UUID
+         * Retrieves a single record by its globally unique UUID. This is intended for public-facing interfaces, since record identifiers aren't sequential and thus cannot be predicted.
          *
          * @generated from rpc Scailo.FamiliesService.ViewByUUID
          */
@@ -616,7 +700,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * View all
+         * Returns all records filtered by their active status.
          *
          * @generated from rpc Scailo.FamiliesService.ViewAll
          */
@@ -627,7 +711,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * View all with the given entity UUID
+         * Returns all records belonging to a specific organization/entity UUID.
          *
          * @generated from rpc Scailo.FamiliesService.ViewAllForEntityUUID
          */
@@ -638,7 +722,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * View with pagination
+         * Retrieves a paginated list of records based on status, sort keys, and offsets.
          *
          * @generated from rpc Scailo.FamiliesService.ViewWithPagination
          */
@@ -671,7 +755,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * View all that match the given search key
+         * Performs a free-text search across records using a search key.
          *
          * @generated from rpc Scailo.FamiliesService.SearchAll
          */
@@ -682,7 +766,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * View all that match the given filter criteria
+         * Performs a high-granularity search based on multiple specific field filters.
          *
          * @generated from rpc Scailo.FamiliesService.Filter
          */
@@ -777,7 +861,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Count in status
+         * Returns the total number of records currently in a specific lifecycle status.
          *
          * @generated from rpc Scailo.FamiliesService.CountInStatus
          */
@@ -788,7 +872,7 @@ exports.FamiliesService = {
             kind: protobuf_1.MethodKind.Unary,
         },
         /**
-         * Count all that match the given criteria
+         * Returns the total count of records matching the given complex filter criteria.
          *
          * @generated from rpc Scailo.FamiliesService.Count
          */