slotlock 0.7.0 → 0.9.0

package/availability-store.d.ts

@@ -0,0 +1,193 @@
+import type { Sql, TransactionSql } from 'postgres';
+import { type SlotlockAvailabilityException, type SlotlockExceptionOutcome, type SlotlockExceptionSource, type SlotlockExceptionWindow, type SlotlockRankedException } from './hours.js';
+import type { SlotlockHoliday } from './holidays.js';
+import type { SlotlockInheritedAvailability, WeeklyAvailabilityRule } from './types.js';
+type StoreSql = Sql | TransactionSql;
+/** The tenant's stored hours and each location's that has them. */
+export interface SlotlockAvailabilityDefaults {
+    tenant: WeeklyAvailabilityRule[] | null;
+    locations: {
+        location: string;
+        rules: WeeklyAvailabilityRule[];
+    }[];
+}
+/**
+ * What storing the tenant's hours does to resources with hours of their own: `none` keeps them,
+ * `all` clears them so every resource inherits, and `matching` clears only those whose hours are
+ * the same as the tenant's were before, or as the hours being stored: the copies an earlier
+ * version (0.8.0 and before) made, while hours set apart on purpose stay.
+ */
+export type SlotlockOverrideResources = 'none' | 'matching' | 'all';
+export declare const SLOTLOCK_OVERRIDE_RESOURCES: readonly SlotlockOverrideResources[];
+/** What setting stored hours changed: resources now on them, and those that keep their own. */
+export interface SlotlockAvailabilityDefaultsResult {
+    /** Resources in use whose hours these now are. */
+    inheriting: number;
+    /** Resources in use the hours reach that keep hours of their own. */
+    ownHours: number;
+}
+export interface SlotlockAvailabilityExceptionInput {
+    tenantRef: string;
+    /** A location: it and every location inside it. */
+    location?: string;
+    /** One resource. Neither: the whole tenant. */
+    resourceId?: string;
+    startsOn: string;
+    /** The last day, inclusive; the first when absent. */
+    endsOn?: string;
+    outcome: SlotlockExceptionOutcome;
+    hours?: readonly SlotlockExceptionWindow[];
+    label: string;
+    source?: SlotlockExceptionSource;
+    /** An import's own id for the exception: importing again updates the same one. */
+    sourceUid?: string;
+    /** The holiday calendar it is imported from (importHolidayCalendar); internal. */
+    calendarId?: string;
+}
+/** Inherited hours as slotlock.inherited_availability gives them; rules that do not parse read as closed. */
+export declare function storedInheritedAvailability(value: unknown): SlotlockInheritedAvailability | undefined;
+/**
+ * Store the tenant's weekly hours (or clear them, `null`): every resource without its own and with
+ * no location hours above it uses them. `overrideResources` says what becomes of the hours
+ * resources keep of their own (SlotlockOverrideResources; `none` by default).
+ */
+export declare function storeTenantAvailability(sql: StoreSql, params: {
+    tenantRef: string;
+    rules: readonly WeeklyAvailabilityRule[] | null;
+    overrideResources?: SlotlockOverrideResources;
+}): Promise<SlotlockAvailabilityDefaultsResult>;
+/**
+ * Store a location's weekly hours (or clear them, `null`): resources at it or inside it without
+ * their own use them, unless a location nearer them has its own. Null for a location the tenant
+ * does not have.
+ */
+export declare function setLocationAvailability(sql: StoreSql, params: {
+    tenantRef: string;
+    location: string;
+    rules: readonly WeeklyAvailabilityRule[] | null;
+}): Promise<SlotlockAvailabilityDefaultsResult | null>;
+export declare function getAvailabilityDefaults(sql: StoreSql, params: {
+    tenantRef: string;
+}): Promise<SlotlockAvailabilityDefaults>;
+/**
+ * Add an exception, or, for an import's `sourceUid` already stored at that scope, update it.
+ * Refuses `invalid_availability_exception`, `location_not_found`, `resource_not_found` and
+ * `availability_exceptions_limit_reached` (SLOTLOCK_MAX_AVAILABILITY_EXCEPTIONS a tenant).
+ */
+export declare function createAvailabilityException(sql: StoreSql, input: SlotlockAvailabilityExceptionInput): Promise<SlotlockAvailabilityException>;
+/**
+ * The tenant's exceptions by first day: those that apply to `resourceId` (the tenant's, its
+ * locations' and its own), or one `location`'s own, or all of them; only those reaching `from` to
+ * `to` when given. Keyset-paginated by `after` (the last one's id).
+ */
+export declare function listAvailabilityExceptions(sql: StoreSql, params: {
+    tenantRef: string;
+    resourceId?: string;
+    location?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+    after?: string;
+}): Promise<SlotlockAvailabilityException[]>;
+export declare function deleteAvailabilityException(sql: StoreSql, params: {
+    tenantRef: string;
+    id: string;
+}): Promise<boolean>;
+/**
+ * Each resource's exceptions that reach local days from `from` to `to` (`YYYY-MM-DD`), ranked as the
+ * evaluator applies them: the tenant's (0), each location's from the outermost in, the resource's
+ * own (1000).
+ */
+export declare function rankedExceptions(sql: StoreSql, resourceIds: readonly string[], days: {
+    from: string;
+    to?: string;
+}): Promise<Map<string, SlotlockRankedException[]>>;
+/**
+ * Replace the exceptions an import of one resource's VAVAILABILITY made with `ranges`. Refuses as
+ * createAvailabilityException does.
+ */
+export declare function replaceImportedExceptions(sql: StoreSql, params: {
+    tenantRef: string;
+    resourceId: string;
+    ranges: readonly {
+        startsOn: string;
+        endsOn: string;
+        outcome: SlotlockExceptionOutcome;
+        hours?: SlotlockExceptionWindow[];
+    }[];
+}): Promise<number>;
+/** A holiday calendar imported into closures (RFC 0004 B1): a pasted or uploaded one, or a subscription. */
+export interface SlotlockHolidayCalendar {
+    id: string;
+    /** Unique at its scope: importing under the same name replaces what that calendar said. */
+    name: string;
+    location?: string;
+    resourceId?: string;
+    /** A subscription's https URL, imported again by maintenance by `nextImportAt`. */
+    url?: string;
+    importedAt?: Date;
+    nextImportAt?: Date;
+    /** Why the last import of a subscription failed; cleared by the next that works. */
+    lastError?: string;
+    /** Its closures. */
+    closures: number;
+    createdAt: Date;
+}
+/** What one import of a holiday calendar did. */
+export interface SlotlockHolidayImport {
+    calendar: SlotlockHolidayCalendar;
+    /** Holidays added or updated. */
+    imported: number;
+    /** Closures this calendar made that it no longer names in the import's span, deleted. */
+    removed: number;
+}
+/** How long a subscription waits between imports, and after a failed one. */
+export declare const SLOTLOCK_HOLIDAY_REIMPORT_DAYS = 30;
+export declare const SLOTLOCK_HOLIDAY_RETRY_HOURS = 24;
+/** Holiday calendars a tenant may keep. */
+export declare const SLOTLOCK_MAX_HOLIDAY_CALENDARS = 50;
+/**
+ * Import a holiday calendar's days off as closures at its scope (the tenant, a location or a
+ * resource), as the calendar named `name` there: each holiday added or updated by its UID, then
+ * the closures this calendar made earlier that it no longer names between `span.from` and
+ * `span.to` deleted, so a holiday it dropped goes too. A closure imported before calendars were
+ * kept, with the UID of one it names, becomes this calendar's. With `url`, the calendar is a
+ * subscription maintenance imports again every SLOTLOCK_HOLIDAY_REIMPORT_DAYS; without, it stops
+ * being one. Refuses `invalid_holiday_calendar`, `location_not_found`, `resource_not_found`,
+ * `holiday_calendars_limit_reached` and `availability_exceptions_limit_reached`.
+ */
+export declare function importHolidayCalendar(sql: StoreSql, params: {
+    tenantRef: string;
+    location?: string;
+    resourceId?: string;
+    name: string;
+    url?: string;
+    holidays: readonly SlotlockHoliday[];
+    span: {
+        from: string;
+        to: string;
+    };
+}): Promise<SlotlockHolidayImport>;
+/** The tenant's holiday calendars, by scope and name. */
+export declare function listHolidayCalendars(sql: StoreSql, params: {
+    tenantRef: string;
+}): Promise<SlotlockHolidayCalendar[]>;
+/** Delete a holiday calendar and its closures. Null for one the tenant does not have. */
+export declare function deleteHolidayCalendar(sql: StoreSql, params: {
+    tenantRef: string;
+    id: string;
+}): Promise<{
+    closures: number;
+} | null>;
+/** Subscriptions due to be imported again, the longest waiting first. */
+export declare function dueHolidayCalendars(sql: StoreSql, params: {
+    tenantRef: string;
+    limit: number;
+}): Promise<SlotlockHolidayCalendar[]>;
+/** Note why a subscription's import failed, and try again in SLOTLOCK_HOLIDAY_RETRY_HOURS. */
+export declare function noteHolidayCalendarFailure(sql: StoreSql, params: {
+    tenantRef: string;
+    id: string;
+    error: string;
+}): Promise<void>;
+export {};