grm-shared-library 1.1.194 → 1.1.196

package/dist/types/modules/partner/interfaces/partner-provider-descriptor.d.ts

@@ -0,0 +1,56 @@
+import { PartnerIntegrationEnvironment } from '../enums/partner-integration-environment.enum';
+import { PartnerProviderCode } from '../enums/partner-provider-code.enum';
+import { PartnerServiceCapability } from '../enums/partner-service-capability.enum';
+/** A credential a partnership must supply before it can dispatch. */
+export interface PartnerProviderCredentialField {
+    /** Stable key the adapter reads, e.g. `apiKey`. */
+    key: string;
+    label: string;
+    description?: string;
+    required: boolean;
+    /**
+     * Always true today, and asserted by the service: a credential is stored as
+     * a REFERENCE to a secret (a Secret Manager name or an env var name), never
+     * as its value.
+     */
+    secret: boolean;
+}
+/** A non-secret setting a partnership must (or may) supply for a provider. */
+export interface PartnerProviderConfigField {
+    /** Stable key inside the partnership configuration object, e.g. `source`. */
+    key: string;
+    label: string;
+    description?: string;
+    required: boolean;
+    type: 'string' | 'number' | 'boolean' | 'enum';
+    /** Permitted values when `type` is `enum`. */
+    allowedValues?: string[];
+    defaultValue?: string | number | boolean;
+    /** Maximum length for string values, when the partner imposes one. */
+    maxLength?: number;
+}
+/**
+ * What one registered partner adapter can do, published by
+ * `GET /partner-services/providers`.
+ *
+ * The adapter registry is the single source of truth for the partner catalogue -
+ * there is deliberately no catalogue table, because a row and an adapter can
+ * drift and a missing adapter is the one thing an operator must never discover
+ * mid-emergency. The admin UI builds its "add a partner" form from these
+ * descriptors.
+ */
+export interface PartnerProviderDescriptor {
+    providerCode: PartnerProviderCode;
+    name: string;
+    description: string;
+    /** Services this partner can be asked for. */
+    capabilities: PartnerServiceCapability[];
+    /** Suggested base URLs per environment; a partnership may override them. */
+    defaultBaseUrls: Partial<Record<PartnerIntegrationEnvironment, string>>;
+    configFields: PartnerProviderConfigField[];
+    credentialFields: PartnerProviderCredentialField[];
+    /** True when the adapter implements a non-mutating connectivity probe. */
+    supportsHealthCheck: boolean;
+    /** False for reserved provider codes that have no working adapter yet. */
+    available: boolean;
+}

package/dist/types/modules/partner/interfaces/partner-routing-result.d.ts

@@ -0,0 +1,24 @@
+import { IncidentPartnerRoutingStatus } from '../enums/incident-partner-routing-status.enum';
+import { IncidentPartnerRoutingEntry } from './incident-partner-routing';
+/**
+ * What clarion-partner-services answers when clarion-incident hands it a newly
+ * created incident.
+ *
+ * Returned synchronously from `POST /partner-services/routing/incidents` so the
+ * caller learns immediately whether any partner was engaged, without having to
+ * wait for the outbound partner call itself: AUTO dispatches are still in flight
+ * when this returns, and their outcome arrives later on the routing callback.
+ */
+export interface PartnerRoutingResult {
+    incidentId: number;
+    organizationId: number;
+    status: IncidentPartnerRoutingStatus;
+    evaluatedAt: string;
+    /** Partnerships that were enabled and in scope for this incident. */
+    consideredIntegrationCount: number;
+    /** Partnerships whose coverage rules matched. */
+    matchedIntegrationCount: number;
+    entries: IncidentPartnerRoutingEntry[];
+    /** True when nothing was created because the incident had already been routed. */
+    idempotentReplay: boolean;
+}

package/dist/types/modules/partner/utils/partner-payload.util.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Trim a value to a partner's field limit without ever throwing.
+ *
+ * Partner APIs reject an over-long field outright, and refusing to send an
+ * emergency because a description ran long is never the right trade - so the
+ * value is truncated and the emergency still goes.
+ */
+export declare function truncateForPartner(value: string | null | undefined, maxLength: number): string | undefined;
+/**
+ * Build the free-text description of what is wrong, from the incident's type,
+ * category and description.
+ *
+ * Ordered most-specific-first so a partner reading only the opening words still
+ * learns the useful part, and clamped to the partner's limit.
+ */
+export declare function buildPartnerIssueText(parts: {
+    typeName?: string | null;
+    categoryName?: string | null;
+    description?: string | null;
+    maxLength?: number;
+}): string | undefined;
+/**
+ * Mask an identifier for logging: keeps enough to correlate, never enough to
+ * reuse. `+254712345678` becomes `+254***5678`.
+ *
+ * Every log line in the partner pipeline goes through this - a dispatch carries
+ * a reporter's phone number and a partner's reference, and neither belongs in
+ * plaintext in a log aggregator.
+ */
+export declare function maskPartnerIdentifier(value: string | null | undefined): string;
+/**
+ * Strip anything credential-shaped out of a value before it is persisted on a
+ * dispatch or written to a log.
+ *
+ * Applied to every partner request and response body the service stores.
+ * Matching is on the KEY, case-insensitively and by substring, because partners
+ * do not agree on a name for a secret (`apiKey`, `api_key`, `access_token`,
+ * `Authorization`, ...). The shape of the payload is preserved so an audit still
+ * shows what was sent.
+ */
+export declare function sanitizePartnerPayload(value: unknown, depth?: number): unknown;
+/**
+ * A URL safe to store on an attempt record: origin and path only, with any
+ * query string replaced.
+ *
+ * Partner APIs put credentials in query strings often enough that keeping one
+ * verbatim in an audit table is a real exposure.
+ */
+export declare function maskPartnerUrl(url: string | null | undefined): string;

package/dist/types/modules/partner/utils/partner-routing.util.d.ts

@@ -0,0 +1,71 @@
+import { IncidentChannel } from '../../incident/enums/incident-channel.enum';
+import { IncidentEmergencyType } from '../../incident/enums/incident-emergency-type.enum';
+import { IncidentPartnerRoutingStatus } from '../enums/incident-partner-routing-status.enum';
+import { PartnerCoverageMatchType } from '../enums/partner-coverage-match-type.enum';
+import { PartnerDispatchFailureReason } from '../enums/partner-dispatch-failure-reason.enum';
+import { PartnerDispatchStatus } from '../enums/partner-dispatch-status.enum';
+import { PartnerLocationProvider } from '../enums/partner-location-provider.enum';
+import { PartnerRoutingMode } from '../enums/partner-routing-mode.enum';
+/** The incident facts a coverage rule is matched against. */
+export interface PartnerCoverageSubject {
+    incidentTypeId?: number | null;
+    incidentCategoryId?: number | null;
+    emergencyType?: IncidentEmergencyType | string | null;
+}
+/** The parts of a coverage rule that decide whether it matches. */
+export interface PartnerCoverageCriteria {
+    matchType: PartnerCoverageMatchType;
+    incidentTypeId?: number | null;
+    incidentCategoryId?: number | null;
+    emergencyType?: IncidentEmergencyType | string | null;
+    enabled?: boolean;
+}
+/**
+ * Whether a coverage rule applies to an incident.
+ *
+ * Shared by clarion-partner-services (which routes on it) and the web admin
+ * (which previews "what would this rule catch?"), so the two can never disagree
+ * about whether an ambulance would have been called.
+ *
+ * A disabled rule never matches, and a rule whose match key is missing on either
+ * side never matches - a rule with no incident type cannot silently become a
+ * catch-all.
+ */
+export declare function coverageRuleMatches(rule: PartnerCoverageCriteria, subject: PartnerCoverageSubject): boolean;
+/**
+ * The routing mode actually applied to a dispatch.
+ *
+ * A rule-level override wins over the partnership's default, and DISABLED at
+ * either level wins over everything - an organization that has switched routing
+ * off must not be overridden by a rule it forgot about.
+ */
+export declare function resolveRoutingMode(integrationMode: PartnerRoutingMode, ruleOverride?: PartnerRoutingMode | null): PartnerRoutingMode;
+/**
+ * How a partner is told the incident's location was obtained, derived from the
+ * reporting channel.
+ *
+ * `overrides` accepts a partnership's `locationProviderByChannel` configuration
+ * verbatim; unknown channels and unknown provider values fall back to the
+ * platform default rather than being passed through to the partner.
+ */
+export declare function mapChannelToLocationProvider(channel?: IncidentChannel | string | null, overrides?: Record<string, string> | null): PartnerLocationProvider;
+/** Type guard for a value claiming to be a {@link PartnerLocationProvider}. */
+export declare function isPartnerLocationProvider(value: unknown): value is PartnerLocationProvider;
+/** Whether a failure should be retried, or has no chance of succeeding. */
+export declare function isPermanentDispatchFailure(reason?: PartnerDispatchFailureReason | null): boolean;
+/** Whether a dispatch status means the partner has the emergency. */
+export declare function isDeliveredDispatchStatus(status: PartnerDispatchStatus): boolean;
+/**
+ * Seconds to wait before retry number `attemptNumber` (1-based), as an
+ * exponential backoff clamped to the configured ceiling.
+ */
+export declare function retryDelaySeconds(attemptNumber: number, baseSeconds?: number, maxSeconds?: number): number;
+/**
+ * Roll every dispatch on an incident up into the one status stored on the
+ * incident row.
+ *
+ * Order matters and encodes what an operator most needs to see first: anything
+ * still waiting on a human outranks a settled outcome, and a mix of delivered
+ * and failed is reported as PARTIALLY_ROUTED rather than rounded to either.
+ */
+export declare function summarizeIncidentRoutingStatus(statuses: PartnerDispatchStatus[]): IncidentPartnerRoutingStatus;

package/dist/types/modules/permission/enums/permission-actions.enum.d.ts

@@ -7,6 +7,10 @@ export declare enum PermissionActions {
     READ_PARTNER = "read:partner",
     UPDATE_PARTNER = "update:partner",
     DELETE_PARTNER = "delete:partner",
+    READ_PARTNER_DISPATCH = "read:partner-dispatch",
+    APPROVE_PARTNER_DISPATCH = "approve:partner-dispatch",
+    CANCEL_PARTNER_DISPATCH = "cancel:partner-dispatch",
+    RESEND_PARTNER_DISPATCH = "resend:partner-dispatch",
     CREATE_CONTROL_CENTRE = "create:control-centre",
     READ_CONTROL_CENTRE = "read:control-centre",
     UPDATE_CONTROL_CENTRE = "update:control-centre",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grm-shared-library",
-  "version": "1.1.194",
+  "version": "1.1.196",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",