swoop-common 2.2.4 → 2.2.7

package/README.md

@@ -1,225 +1,225 @@
-# Swoop Library
-
-This library is used for rendering **Swoop itinerary templates**.
-It provides tools for defining **custom field types**, registering **custom components**,
-rendering templates from a **MasterSchema**, and includes SDKs for all related services.
-It supports both input mode (for creating templates) and presentation mode (for rendering them for end users).
-The schema system is stage-aware, enabling precise control over what data is editable or displayed at which stage.
-
-> Note: This package is intended for internal use only.
-
----
-
-# Swoop Library
-
-## Initialization
-
-Before using the Swoop Library, you must initialize it with service URLs:
-
-```ts
-import { init } from "swoop-common";
-
-init({
-  coreServiceUrl: "https://your.core.service",
-  swoopServiceForwardUrl: "https://your.forward.service",
-});
-```
-
-## Service Interfaces
-
-The library provides three primary service interfaces to interact with backend systems:
-
-- **SwoopService** — Interfaces with the Swoop API.
-- **CoreService** — For core service.
-
-These interfaces offer convenient methods to work seamlessly with the underlying services required by the itinerary system.
-
-## StyledFormView
-
-The `StyledFormView` component is the entry point for rendering a full itinerary template. It handles schema parsing and renderer injection based on mode and form stage.
-
-```tsx
-import { StyledFormView } from "your-form-library";
-
-<StyledFormView
-  initialData={/* object */}
-  schema={/* MasterSchema */}
-  onChange={(val) => console.log(val)}
-  pool="FORM"
-  readonly={false}
-  stage="Inst"
-/>;
-```
-
-### Props
-
-| Name        | Type                 | Description                                                        |
-| ----------- | -------------------- | ------------------------------------------------------------------ |
-| initialData | `any`                | Initial values for the template. Should not be updated frequently. |
-| schema      | `MasterSchema`       | Template definition object.                                        |
-| onChange    | `(val: any) => void` | Callback with updated data.                                        |
-| pool        | `ComponentPool`      | `"FORM"` or `"PRESENTATION"` depending on context.                 |
-| readonly    | `boolean`            | Disables inputs if true (only relevant in FORM pool).              |
-| stage       | `Stage`              | Controls which data segment is being rendered.                     |
-
-### Stages
-
-The template system is divided into stages:
-
-- **Stage.Comp** – Data stored on the root component, often static (e.g. metadata, titles). Does not include any dynamic or time-based fields.
-- **Stage.Inst** – Instance-specific data (e.g. timings, localized notes). This is the most common stage for editable fields.
-- **Stage.User** – Data unique to individual users (e.g. room number).
-
-Each stage builds on the one before it. For example, `Stage.User` includes everything from `Stage.Comp` and `Stage.Inst`. Fields are editable based on the current stage. If a value is defined in two stages, the lower stage will take priority.
-
----
-
-## Custom Components
-
-Custom components define how individual fields render. These can behave like typical form inputs or be used for display-only formatting in the `PRESENTATION` pool.
-
-### Example
-
-```tsx
-const FormExample: React.FC<Props> = ({
-  text,
-  onChange,
-  getError,
-  label,
-  enabled,
-}) => {
-  const [val, setVal] = useState(text);
-  const error = getError ? getError("example")?.message : undefined;
-  const onChangeDebounced = useMemo(() => debounce(onChange, 300), [onChange]);
-
-  const update = (value: string) => {
-    setVal(value);
-    onChangeDebounced(value);
-  };
-
-  return (
-    <Paper
-      sx={{
-        display: "flex",
-        flexDirection: "column",
-        gap: 1,
-        p: 2,
-        background: "#CBC3E3",
-        mb: 1,
-      }}
-    >
-      {!enabled && "THIS IS DISABLED"}
-      <Typography variant="h6">{label}</Typography>
-      <TextField
-        label="Example label"
-        value={val}
-        onChange={(e) => update(e.target.value)}
-        error={!!error}
-        helperText={error}
-        disabled={!enabled}
-      />
-    </Paper>
-  );
-};
-
-const FormRendererExample: React.FC<ControlProps> = ({
-  data,
-  handleChange,
-  path,
-  label,
-  enabled,
-}) => {
-  const getError = useLocalErrors(path);
-  return (
-    <FormExample
-      text={data as string}
-      onChange={(val) => handleChange(path, val)}
-      getError={getError}
-      label={label}
-      enabled={enabled}
-    />
-  );
-};
-
-registerComponent("example", FormRendererExample, ComponentPool.FORM);
-registerComponent("example", FormRendererExample, ComponentPool.PRESENTATION);
-```
-
-> Important: You **cannot register two components with the same name within the same pool**. You _can_ register the same component name across different pools (e.g., `"example"` in both `"FORM"` and `"PRESENTATION"`).
-
-### Presentation Pool
-
-The `PRESENTATION` pool is more than just read-only. It is designed for **customer-facing output**, rendering fields in a clean, non-form-like layout for readability and professionalism.
-
----
-
-## Custom Types
-
-Custom field types define what kinds of fields can be used when **building a template**. These appear in the template builder UI as selectable field types and control how data is validated and configured.
-
-### Syntax
-
-```ts
-registerType(
-  "typeId", // Unique type string
-  "Display Name", // Name shown in template builder
-  schema, // JSON Schema defining the data structure
-  optionsSchema, // JSON Schema defining configuration data structure
-  requiredOptions // boolean: must the options be filled?
-);
-```
-
-### Example
-
-```ts
-registerType(
-  "enum",
-  "Dropdown",
-  { type: "array" },
-  {
-    type: "object",
-    title: "Dropdown Options",
-    properties: {
-      enumValues: {
-        title: "Dropdown Values",
-        type: "array",
-        items: { type: "string" },
-      },
-    },
-  },
-  true
-);
-```
-
-This type defines a dropdown field where the values are defined via the `enumValues` property in the template configuration.
-
-### Custom Option Editors
-
-If you want to render a **custom options block** (i.e., how the field type's options are displayed in the template editor), you must do the following:
-
-1. In the top-level `optionsSchema` of the type, define `"x-type": "yourTypeName"`
-2. Create and register a custom component with the name `"yourTypeName"` in the `"FORM"` pool.
-
-This component will then be used to render the configuration UI for that field type.
-
----
-
-## File Locations
-
-- **Custom components** must be placed in `src/renderers`. They may be nested within subfolders. All files inside `renderers/` will be automatically imported in the correct order.
-- **Custom types** must be added to `src/default_registration/fields_base.tsx`.
-
-No manual import wiring is required beyond placing the file in the correct folder.
-
----
-
-## Publishing to NPM
-
-To publish a new version of the package:
-
-```bash
-npm run build             # Compile the package
-npm version patch         # Bump the patch version (or use minor/major as needed)
-npm adduser               # Log in to NPM (if not already)
-npm publish               # Publish the package
-```
+.# Swoop Library
+
+This library is used for rendering **Swoop itinerary templates**.
+It provides tools for defining **custom field types**, registering **custom components**,
+rendering templates from a **MasterSchema**, and includes SDKs for all related services.
+It supports both input mode (for creating templates) and presentation mode (for rendering them for end users).
+The schema system is stage-aware, enabling precise control over what data is editable or displayed at which stage.
+
+> Note: This package is intended for internal use only.
+
+---
+
+# Swoop Library
+
+## Initialization
+
+Before using the Swoop Library, you must initialize it with service URLs:
+
+```ts
+import { init } from "swoop-common";
+
+init({
+  coreServiceUrl: "https://your.core.service",
+  swoopServiceForwardUrl: "https://your.forward.service",
+});
+```
+
+## Service Interfaces
+
+The library provides three primary service interfaces to interact with backend systems:
+
+- **SwoopService** — Interfaces with the Swoop API.
+- **CoreService** — For core service.
+
+These interfaces offer convenient methods to work seamlessly with the underlying services required by the itinerary system.
+
+## StyledFormView
+
+The `StyledFormView` component is the entry point for rendering a full itinerary template. It handles schema parsing and renderer injection based on mode and form stage.
+
+```tsx
+import { StyledFormView } from "your-form-library";
+
+<StyledFormView
+  initialData={/* object */}
+  schema={/* MasterSchema */}
+  onChange={(val) => console.log(val)}
+  pool="FORM"
+  readonly={false}
+  stage="Inst"
+/>;
+```
+
+### Props
+
+| Name        | Type                 | Description                                                        |
+| ----------- | -------------------- | ------------------------------------------------------------------ |
+| initialData | `any`                | Initial values for the template. Should not be updated frequently. |
+| schema      | `MasterSchema`       | Template definition object.                                        |
+| onChange    | `(val: any) => void` | Callback with updated data.                                        |
+| pool        | `ComponentPool`      | `"FORM"` or `"PRESENTATION"` depending on context.                 |
+| readonly    | `boolean`            | Disables inputs if true (only relevant in FORM pool).              |
+| stage       | `Stage`              | Controls which data segment is being rendered.                     |
+
+### Stages
+
+The template system is divided into stages:
+
+- **Stage.Comp** – Data stored on the root component, often static (e.g. metadata, titles). Does not include any dynamic or time-based fields.
+- **Stage.Inst** – Instance-specific data (e.g. timings, localized notes). This is the most common stage for editable fields.
+- **Stage.User** – Data unique to individual users (e.g. room number).
+
+Each stage builds on the one before it. For example, `Stage.User` includes everything from `Stage.Comp` and `Stage.Inst`. Fields are editable based on the current stage. If a value is defined in two stages, the lower stage will take priority.
+
+---
+
+## Custom Components
+
+Custom components define how individual fields render. These can behave like typical form inputs or be used for display-only formatting in the `PRESENTATION` pool.
+
+### Example
+
+```tsx
+const FormExample: React.FC<Props> = ({
+  text,
+  onChange,
+  getError,
+  label,
+  enabled,
+}) => {
+  const [val, setVal] = useState(text);
+  const error = getError ? getError("example")?.message : undefined;
+  const onChangeDebounced = useMemo(() => debounce(onChange, 300), [onChange]);
+
+  const update = (value: string) => {
+    setVal(value);
+    onChangeDebounced(value);
+  };
+
+  return (
+    <Paper
+      sx={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 1,
+        p: 2,
+        background: "#CBC3E3",
+        mb: 1,
+      }}
+    >
+      {!enabled && "THIS IS DISABLED"}
+      <Typography variant="h6">{label}</Typography>
+      <TextField
+        label="Example label"
+        value={val}
+        onChange={(e) => update(e.target.value)}
+        error={!!error}
+        helperText={error}
+        disabled={!enabled}
+      />
+    </Paper>
+  );
+};
+
+const FormRendererExample: React.FC<ControlProps> = ({
+  data,
+  handleChange,
+  path,
+  label,
+  enabled,
+}) => {
+  const getError = useLocalErrors(path);
+  return (
+    <FormExample
+      text={data as string}
+      onChange={(val) => handleChange(path, val)}
+      getError={getError}
+      label={label}
+      enabled={enabled}
+    />
+  );
+};
+
+registerComponent("example", FormRendererExample, ComponentPool.FORM);
+registerComponent("example", FormRendererExample, ComponentPool.PRESENTATION);
+```
+
+> Important: You **cannot register two components with the same name within the same pool**. You _can_ register the same component name across different pools (e.g., `"example"` in both `"FORM"` and `"PRESENTATION"`).
+
+### Presentation Pool
+
+The `PRESENTATION` pool is more than just read-only. It is designed for **customer-facing output**, rendering fields in a clean, non-form-like layout for readability and professionalism.
+
+---
+
+## Custom Types
+
+Custom field types define what kinds of fields can be used when **building a template**. These appear in the template builder UI as selectable field types and control how data is validated and configured.
+
+### Syntax
+
+```ts
+registerType(
+  "typeId", // Unique type string
+  "Display Name", // Name shown in template builder
+  schema, // JSON Schema defining the data structure
+  optionsSchema, // JSON Schema defining configuration data structure
+  requiredOptions // boolean: must the options be filled?
+);
+```
+
+### Example
+
+```ts
+registerType(
+  "enum",
+  "Dropdown",
+  { type: "array" },
+  {
+    type: "object",
+    title: "Dropdown Options",
+    properties: {
+      enumValues: {
+        title: "Dropdown Values",
+        type: "array",
+        items: { type: "string" },
+      },
+    },
+  },
+  true
+);
+```
+
+This type defines a dropdown field where the values are defined via the `enumValues` property in the template configuration.
+
+### Custom Option Editors
+
+If you want to render a **custom options block** (i.e., how the field type's options are displayed in the template editor), you must do the following:
+
+1. In the top-level `optionsSchema` of the type, define `"x-type": "yourTypeName"`
+2. Create and register a custom component with the name `"yourTypeName"` in the `"FORM"` pool.
+
+This component will then be used to render the configuration UI for that field type.
+
+---
+
+## File Locations
+
+- **Custom components** must be placed in `src/renderers`. They may be nested within subfolders. All files inside `renderers/` will be automatically imported in the correct order.
+- **Custom types** must be added to `src/default_registration/fields_base.tsx`.
+
+No manual import wiring is required beyond placing the file in the correct folder.
+
+---
+
+## Publishing to NPM
+
+To publish a new version of the package:
+
+```bash
+npm run build             # Compile the package
+npm version patch         # Bump the patch version (or use minor/major as needed)
+npm adduser               # Log in to NPM (if not already)
+npm publish               # Publish the package
+```

package/dist/api/generated/core/exports.d.ts

@@ -3,7 +3,6 @@ export { CancelablePromise, CancelError } from './index';
 export type { Amendment } from './index';
 export type { AssignedPassenger } from './index';
 export type { AssignedTravellerGroup } from './index';
-export type { B64StringQueryParam } from './index';
 export { BookingStatus } from './index';
 export type { Branches } from './index';
 export type { BranchId } from './index';

package/dist/api/generated/core/index.d.ts

@@ -5,7 +5,6 @@ export type { OpenAPIConfig } from './core/OpenAPI';
 export type { Amendment } from './models/Amendment';
 export type { AssignedPassenger } from './models/AssignedPassenger';
 export type { AssignedTravellerGroup } from './models/AssignedTravellerGroup';
-export type { B64StringQueryParam } from './models/B64StringQueryParam';
 export { BookingStatus } from './models/BookingStatus';
 export type { Branches } from './models/Branches';
 export type { BranchId } from './models/BranchId';
@@ -97,7 +96,6 @@ export { UrgencyCTA } from './models/UrgencyCTA';
 export type { UserComponentInstanceField } from './models/UserComponentInstanceField';
 export type { ValidationSchemas } from './models/ValidationSchemas';
 export type { VersionPathParam } from './models/VersionPathParam';
-export { AuditService } from './services/AuditService';
 export { ComponentService } from './services/ComponentService';
 export { CoreService } from './services/CoreService';
 export { ItineraryService } from './services/ItineraryService';

package/dist/api/generated/core/index.js

@@ -13,7 +13,6 @@ export { Meals } from './models/Meals';
 export { OrderQueryParam } from './models/OrderQueryParam';
 export { OrgId } from './models/OrgId';
 export { UrgencyCTA } from './models/UrgencyCTA';
-export { AuditService } from './services/AuditService';
 export { ComponentService } from './services/ComponentService';
 export { CoreService } from './services/CoreService';
 export { ItineraryService } from './services/ItineraryService';

package/dist/api/generated/core/models/SortQueryParam.d.ts

@@ -1,4 +1,4 @@
 /**
  * List of fields to sort by, this requires the order query param
  */
-export type SortQueryParam = any[];
+export type SortQueryParam = Array<string>;

package/dist/api/generated/core/models/SwooperPersonalInfo.d.ts

@@ -1,7 +1,7 @@
 import type { SwooperHighlights } from './SwooperHighlights';
 export type SwooperPersonalInfo = {
-    highlights?: SwooperHighlights;
-    interests?: Array<string>;
-    dayToDay?: string;
-    startedInTravel?: number;
+    highlights: SwooperHighlights;
+    interests: Array<string>;
+    dayToDay: string;
+    startedInTravel: number;
 };

package/dist/api/generated/core/services/ComponentService.d.ts

@@ -15,12 +15,12 @@ export declare class ComponentService {
      * @param sort List of fields to sort by, this requires the order query param
      * @param search The search strings to apply to the on query parameter values
      * @param on The fields to apply the search to, the list follows the order and length of the search values in the search query
-     * @returns any The list of all component given the parameters used
+     * @returns any Paginated response of components
      * @throws ApiError
      */
-    static componentList(page?: number, limit?: number, order?: 'asc' | 'desc', sort?: any[], search?: Array<string>, on?: Array<string>): CancelablePromise<{
-        data?: Array<DTOComponentRead>;
+    static componentList(page?: number, limit?: number, order?: 'asc' | 'desc', sort?: Array<string>, search?: Array<string>, on?: Array<string>): CancelablePromise<{
         pagination?: Pagination;
+        data?: Array<DTOComponentRead>;
     }>;
     /**
      * Create a Component
@@ -69,8 +69,8 @@ export declare class ComponentService {
      * Directly update component state. This does not create a new revision
      * @param componentId Id of a component
      * @param state The publishing state of the component
-     * @returns any OK
+     * @returns DTOComponentRead When the state was updated successfully
      * @throws ApiError
      */
-    static componentStateUpdate(componentId: ComponentId, state: ComponentState): CancelablePromise<any>;
+    static componentStateUpdate(componentId: ComponentId, state: ComponentState): CancelablePromise<DTOComponentRead>;
 }

package/dist/api/generated/core/services/ComponentService.js

@@ -10,7 +10,7 @@ export class ComponentService {
      * @param sort List of fields to sort by, this requires the order query param
      * @param search The search strings to apply to the on query parameter values
      * @param on The fields to apply the search to, the list follows the order and length of the search values in the search query
-     * @returns any The list of all component given the parameters used
+     * @returns any Paginated response of components
      * @throws ApiError
      */
     static componentList(page, limit, order, sort, search, on) {
@@ -26,10 +26,9 @@ export class ComponentService {
                 'on': on,
             },
             errors: {
-                400: `If the filter options or query parameters contain invalid values`,
-                401: `Unauthorized - Missing or invalid Authorization header`,
-                403: `Forbidden - The client is authenticated but not authorized to access this resource`,
-                500: `When an internal server error occurs when listing all related component`,
+                400: `If the payload is malformed`,
+                401: `When the client is not authorised`,
+                500: `When an unexpected error occurs`,
             },
         });
     }
@@ -69,9 +68,10 @@ export class ComponentService {
                 'componentId': componentId,
             },
             errors: {
-                401: `Missing or invalid Authorization header`,
-                403: `The client is authenticated but not authorized to access this resource`,
-                404: `If a resource is not found`,
+                400: `If the payload is malformed`,
+                401: `Unauthorized - Missing or invalid Authorization header`,
+                403: `Forbidden - The client is authenticated but not authorized to access this resource`,
+                404: `If a resource does not exist`,
                 500: `Internal Server Error`,
             },
         });
@@ -97,8 +97,8 @@ export class ComponentService {
                 400: `If the payload is malformed`,
                 401: `Unauthorized - Missing or invalid Authorization header`,
                 403: `Forbidden - The client is authenticated but not authorized to access this resource`,
-                404: `When the component id to create a new revision from is not found`,
-                500: `When an internal server error occurs updating a component as a new revision`,
+                404: `If a resource does not exist`,
+                500: `Internal Server Error`,
             },
         });
     }
@@ -123,8 +123,8 @@ export class ComponentService {
                 400: `If the payload is malformed`,
                 401: `Unauthorized - Missing or invalid Authorization header`,
                 403: `Forbidden - The client is authenticated but not authorized to access this resource`,
-                404: `When the component id to update is not found`,
-                500: `When an internal server error occurs updating a component`,
+                404: `If a resource does not exist`,
+                500: `Internal Server Error`,
             },
         });
     }
@@ -143,11 +143,11 @@ export class ComponentService {
                 'componentId': componentId,
             },
             errors: {
-                400: `When the component doesn't exist in the first place, or when a before hook fails before deleting the item`,
+                400: `If the payload is malformed`,
                 401: `Unauthorized - Missing or invalid Authorization header`,
                 403: `Forbidden - The client is authenticated but not authorized to access this resource`,
-                404: `Not Found`,
-                500: `When the component fails to delete due to an internal server error`,
+                404: `If a resource does not exist`,
+                500: `Internal Server Error`,
             },
         });
     }
@@ -156,7 +156,7 @@ export class ComponentService {
      * Directly update component state. This does not create a new revision
      * @param componentId Id of a component
      * @param state The publishing state of the component
-     * @returns any OK
+     * @returns DTOComponentRead When the state was updated successfully
      * @throws ApiError
      */
     static componentStateUpdate(componentId, state) {
@@ -170,9 +170,11 @@ export class ComponentService {
                 'state': state,
             },
             errors: {
+                400: `If the payload is malformed`,
                 401: `Unauthorized - Missing or invalid Authorization header`,
                 403: `Forbidden - The client is authenticated but not authorized to access this resource`,
-                404: `Not Found`,
+                404: `If a resource does not exist`,
+                500: `Internal Server Error`,
             },
         });
     }