@jsm-mit/sultana-agent-tools-package 0.2.0

package/dist/salon-core-port.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Everything the tools are allowed to do to a salon, in plain JSON.
+ *
+ * Two reasons this port exists instead of the tools calling the canister wrapper directly:
+ * the tools become testable without a replica, and no `bigint`, `Principal` or candid variant can
+ * leak into a tool result — a model has to be able to read every value it is shown.
+ *
+ * The port is **salon-scoped**: the implementation carries the salon id, so no method takes one.
+ * That is what makes it impossible for a model to address another salon.
+ */
+/**
+ * Whose view of the salon a read returns. `"owner"` is the whole salon — switched-off services and
+ * draft promos included — and needs the owner's identity. `"public"` is what a visitor sees: ACTIVE
+ * services and ACTIVE promos only, readable without any identity.
+ */
+export type SalonAccess = "owner" | "public";
+export interface ServiceView {
+    id: string;
+    name: string;
+    /** Whole zloty — the canister stores an integer and so do we. */
+    pricePln: number;
+    /** Always a multiple of 5. */
+    durationMinutes: number;
+    active: boolean;
+    serviceTypeIds: string[];
+    /** Worker principals as text. */
+    workerIds: string[];
+}
+/** The full set of fields `updateSalonService` replaces. Every write goes through this shape so a
+ * partial edit has to be merged explicitly rather than by accident. */
+export interface ServiceWriteInput {
+    name: string;
+    pricePln: number;
+    durationMinutes: number;
+    active: boolean;
+    serviceTypeIds: string[];
+    workerIds: string[];
+}
+export interface WorkerView {
+    id: string;
+    name: string;
+    /** False while the worker has not claimed their account with the code yet. */
+    linked: boolean;
+}
+export interface ServiceTypeView {
+    id: string;
+    /** Label in the requested language. */
+    label: string;
+    category: string | null;
+}
+export interface SalonCorePort extends SalonSchedulePort, SalonPromoPort {
+    listServices(): Promise<ServiceView[]>;
+    addService(input: ServiceWriteInput): Promise<string>;
+    updateService(serviceId: string, input: ServiceWriteInput): Promise<void>;
+    removeService(serviceId: string): Promise<void>;
+    listWorkers(): Promise<WorkerView[]>;
+    /** Catalog search — the same matcher both frontends use, so the agent and the UI agree on
+     * what "strzyżenie" means. An empty query returns the whole catalog. */
+    findServiceTypes(query: string): Promise<ServiceTypeView[]>;
+}
+/** A window of the day, `"HH:mm"` on both ends. The canister wrapper speaks exactly this shape. */
+export interface TimeRange {
+    startTime: string;
+    endTime: string;
+}
+/**
+ * Scheduling, which has one trap worth naming: the **weekly template stores working hours**, while
+ * a **daily override stores busy hours**. The canister models them that way and the wrapper passes
+ * it straight through, so the port keeps the two words apart rather than calling both "hours".
+ */
+export interface SalonSchedulePort {
+    /** Working windows for one weekday. 0 = Monday … 6 = Sunday. */
+    getWeeklyHours(workerId: string, day: number): Promise<TimeRange[]>;
+    setWeeklyHours(workerId: string, day: number, ranges: TimeRange[]): Promise<void>;
+    /** Busy windows overriding the template for one date (`"YYYY-MM-DD"`). */
+    getDailyBusy(workerId: string, date: string): Promise<TimeRange[]>;
+    setDailyBusy(workerId: string, date: string, ranges: TimeRange[]): Promise<void>;
+    /** Marks the whole date busy. */
+    setDayOff(workerId: string, date: string): Promise<void>;
+    /** Drops the override, so the weekly template applies again. */
+    clearDailyOverride(workerId: string, date: string): Promise<void>;
+}
+export interface MediaView {
+    assetId: string;
+    name: string;
+    kind: "image" | "video" | "audio";
+}
+export interface PromoView {
+    id: string;
+    name: string;
+    active: boolean;
+    assetId: string;
+    textLines: string[];
+    chips: string[];
+    buttonLabel?: string;
+    discountCode?: string;
+    /** The service a tap leads to; absent = the salon itself. */
+    targetServiceId?: string;
+    /** A promo rendered over a music track. The tools never build one — they only carry it
+     * through an edit, because the canister replaces the whole record. */
+    hasMusic: boolean;
+    /** The music record itself, opaque to the tools and passed back verbatim on an edit. */
+    music?: unknown;
+}
+/** Everything `updatePromo` replaces. `music` is opaque here on purpose: it is read from the
+ * current promo and written back untouched, never composed by a tool. */
+export interface PromoWriteInput {
+    name: string;
+    assetId: string;
+    textLines: string[];
+    chips: string[];
+    buttonLabel?: string;
+    discountCode?: string;
+    targetServiceId?: string;
+    music?: unknown;
+}
+export interface DiscountCodeView {
+    code: string;
+    /** Either `{percent}` or `{amountPln}` — exactly one is set. */
+    percent?: number;
+    amountPln?: number;
+    /** The service the code is limited to; absent = the whole salon. */
+    scopeServiceId?: string;
+}
+export interface DiscountCodeInput {
+    code: string;
+    percent?: number;
+    amountPln?: number;
+    scopeServiceId?: string;
+}
+/** The promo library and the discount codes it can broadcast. */
+export interface SalonPromoPort {
+    /** Ready images and videos of the salon's library — what a promo can be built on. */
+    listMedia(): Promise<MediaView[]>;
+    listPromos(): Promise<PromoView[]>;
+    addPromo(input: PromoWriteInput): Promise<string>;
+    updatePromo(promoId: string, input: PromoWriteInput): Promise<void>;
+    setPromoActive(promoId: string, active: boolean): Promise<void>;
+    removePromo(promoId: string): Promise<void>;
+    listDiscountCodes(): Promise<DiscountCodeView[]>;
+    addDiscountCode(input: DiscountCodeInput): Promise<void>;
+    removeDiscountCode(code: string): Promise<void>;
+}
+//# sourceMappingURL=salon-core-port.d.ts.map

package/dist/salon-core-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"salon-core-port.d.ts","sourceRoot":"","sources":["../src/salon-core-port.ts"],"names":[],"mappings":"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"}

package/dist/salon-core-port.js

@@ -0,0 +1,11 @@
+/**
+ * Everything the tools are allowed to do to a salon, in plain JSON.
+ *
+ * Two reasons this port exists instead of the tools calling the canister wrapper directly:
+ * the tools become testable without a replica, and no `bigint`, `Principal` or candid variant can
+ * leak into a tool result — a model has to be able to read every value it is shown.
+ *
+ * The port is **salon-scoped**: the implementation carries the salon id, so no method takes one.
+ * That is what makes it impossible for a model to address another salon.
+ */
+export {};

package/dist/tools/args.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Argument reading for tool calls. A model sends whatever it likes — a number as a string, a
+ * single value where a list belongs, `null` for "unset" — so every read is forgiving about the
+ * shape and strict about the value.
+ *
+ * Each reader throws `ArgumentError`; tool bodies turn that into a `status: "error"` result.
+ */
+export declare class ArgumentError extends Error {
+}
+export declare function readOptionalString(args: Record<string, unknown>, key: string): string | undefined;
+export declare function readString(args: Record<string, unknown>, key: string): string;
+export declare function readOptionalNumber(args: Record<string, unknown>, key: string): number | undefined;
+export declare function readNumber(args: Record<string, unknown>, key: string): number;
+/** Absent means "not confirmed" — never "assume yes". */
+export declare function readBoolean(args: Record<string, unknown>, key: string): boolean;
+export declare function readOptionalStringArray(args: Record<string, unknown>, key: string): string[] | undefined;
+export interface NormalizedNumber {
+    value: number;
+    /** Set when the value had to be adjusted — the agent must tell the owner about it. */
+    note?: string;
+}
+/** The canister stores a price as an integer of whole zloty. */
+export declare function normalizePrice(pricePln: number): NormalizedNumber;
+/** Availability is a grid of 5-minute slots, so a duration that is not a multiple of 5 cannot be
+ * booked. Rounding up rather than down — a service that overruns its slot is worse than one that
+ * ends early. */
+export declare function normalizeDuration(durationMinutes: number): NormalizedNumber;
+/** Confirmation phrases are compared the way a person types them: case and spacing do not count. */
+export declare function phrasesMatch(typed: string, expected: string): boolean;
+//# sourceMappingURL=args.d.ts.map

package/dist/tools/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/tools/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAE3C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOjG;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQjG;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAK/E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAgBxG;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAOjE;AAED;;iBAEiB;AACjB,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,GAAG,gBAAgB,CAO3E;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGrE"}

package/dist/tools/args.js

@@ -0,0 +1,89 @@
+/**
+ * Argument reading for tool calls. A model sends whatever it likes — a number as a string, a
+ * single value where a list belongs, `null` for "unset" — so every read is forgiving about the
+ * shape and strict about the value.
+ *
+ * Each reader throws `ArgumentError`; tool bodies turn that into a `status: "error"` result.
+ */
+export class ArgumentError extends Error {
+}
+export function readOptionalString(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value !== "string")
+        throw new ArgumentError(`Pole "${key}" musi być tekstem.`);
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+export function readString(args, key) {
+    const value = readOptionalString(args, key);
+    if (value === undefined)
+        throw new ArgumentError(`Brakuje pola "${key}".`);
+    return value;
+}
+export function readOptionalNumber(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number(String(value).replace(",", "."));
+    if (!Number.isFinite(parsed))
+        throw new ArgumentError(`Pole "${key}" musi być liczbą.`);
+    return parsed;
+}
+export function readNumber(args, key) {
+    const value = readOptionalNumber(args, key);
+    if (value === undefined)
+        throw new ArgumentError(`Brakuje pola "${key}".`);
+    return value;
+}
+/** Absent means "not confirmed" — never "assume yes". */
+export function readBoolean(args, key) {
+    const value = args[key];
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return value.trim().toLowerCase() === "true";
+    return false;
+}
+export function readOptionalStringArray(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    // A model that has exactly one id often sends it bare instead of in a list.
+    const list = Array.isArray(value) ? value : [value];
+    const items = [];
+    for (const entry of list) {
+        if (typeof entry !== "string")
+            throw new ArgumentError(`Pole "${key}" musi być listą tekstów.`);
+        const trimmed = entry.trim();
+        if (trimmed !== "")
+            items.push(trimmed);
+    }
+    return items;
+}
+/** The canister stores a price as an integer of whole zloty. */
+export function normalizePrice(pricePln) {
+    if (pricePln < 0)
+        throw new ArgumentError("Cena nie może być ujemna.");
+    const rounded = Math.round(pricePln);
+    if (rounded === pricePln)
+        return { value: rounded };
+    return { value: rounded, note: `cenę ${pricePln} zł zaokrąglono do ${rounded} zł` };
+}
+/** Availability is a grid of 5-minute slots, so a duration that is not a multiple of 5 cannot be
+ * booked. Rounding up rather than down — a service that overruns its slot is worse than one that
+ * ends early. */
+export function normalizeDuration(durationMinutes) {
+    if (durationMinutes < 5)
+        throw new ArgumentError("Czas trwania musi wynosić co najmniej 5 minut.");
+    const rounded = Math.ceil(durationMinutes / 5) * 5;
+    if (rounded === durationMinutes)
+        return { value: rounded };
+    return { value: rounded, note: `czas ${durationMinutes} min zaokrąglono w górę do ${rounded} min` };
+}
+/** Confirmation phrases are compared the way a person types them: case and spacing do not count. */
+export function phrasesMatch(typed, expected) {
+    const fold = (text) => text.trim().toLowerCase().replace(/\s+/g, " ");
+    return fold(typed) === fold(expected);
+}

package/dist/tools/promos.d.ts

@@ -0,0 +1,7 @@
+import type { SalonAccess, SalonCorePort } from "../salon-core-port.js";
+import { type AgentTool } from "../types.js";
+export declare function createPromoTools(port: SalonCorePort): AgentTool[];
+/** `access` must match the port: `"public"` only for a port read anonymously, because the canister
+ * gives the salon's owner the whole library whatever the port calls. */
+export declare function listPromosTool(port: SalonCorePort, access?: SalonAccess): AgentTool;
+//# sourceMappingURL=promos.d.ts.map

package/dist/tools/promos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promos.d.ts","sourceRoot":"","sources":["../../src/tools/promos.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA8B,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACpG,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAqBzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,CAYjE;AA2CD;wEACwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,WAAqB,GAAG,SAAS,CAmB5F"}