@jsm-mit/sultana-core-motoko-package 0.0.2 → 0.0.3

package/README.md

@@ -1,3 +1,76 @@
 # Sultana Core Motoko Package
 
-A TypeScript library for interacting with the Sultana Core Motoko actor on the Internet Computer (IC) platform. 
+A TypeScript library for interacting with the Sultana Core Motoko actor on the Internet Computer (IC) platform.
+
+## Setup
+
+### 1. Create dfx identities
+
+Create the required identities:
+
+```bash
+dfx identity new superadmin
+dfx identity new owner1
+dfx identity new worker1
+dfx identity new customer1
+```
+
+### 2. Export PEM values
+
+Export the PEM for each identity and copy the output:
+
+```bash
+dfx identity export superadmin
+dfx identity export owner1
+dfx identity export worker1
+dfx identity export customer1
+```
+
+### 3. Configure .env
+
+Paste each PEM value into the corresponding variable in your `.env` file:
+
+```env
+IDENTITY_PEM="-----BEGIN EC PRIVATE KEY-----
+...superadmin PEM here...
+-----END EC PRIVATE KEY-----"
+
+OWNER1_PEM="-----BEGIN EC PRIVATE KEY-----
+...owner1 PEM here...
+-----END EC PRIVATE KEY-----"
+
+WORKER1_PEM="-----BEGIN EC PRIVATE KEY-----
+...worker1 PEM here...
+-----END EC PRIVATE KEY-----"
+
+CUSTOMER1_PEM="-----BEGIN EC PRIVATE KEY-----
+...customer1 PEM here...
+-----END EC PRIVATE KEY-----"
+```
+
+> Make sure to keep newlines inside the PEM value — wrap the value in double quotes and preserve the line breaks exactly as exported.
+
+## Tests
+
+Tests are integration tests that run against a dedicated test canister on **mainnet** — no local replica is used.
+
+### Prerequisites
+
+Complete the [Setup](#setup) section first. Then copy `.env.example` to `.env` and fill in `CANISTER_ID` and all PEM values.
+
+### Available test scripts
+
+Each script redeploys the test canister before running.
+
+| Script | Description |
+|---|---|
+| `npm run test-suite` | Full integration test — covers admin, profiles, service types, salons, HR, availability, booking, search, and visits |
+| `npm run test-tomorrow` | Same as `test-suite` but with `referenceDate` set to tomorrow |
+| `npm run test-access-restrictions` | Role-based access control tests |
+| `npm run test-migration-simple` | Data migration tests |
+
+### Notes
+
+- Tests require an active internet connection and a valid `CANISTER_ID` in `.env`.
+- After any write (update call), the IC needs a moment to propagate state — tests include a `waitFor(5000)` delay before subsequent reads to avoid non-deterministic results.
+- **If a test fails, the first thing to check is whether state had enough time to propagate.** Rerun the test before investigating logic errors — transient propagation lag is the most common cause of false failures on mainnet.

package/declarations/sultana-core-motoko/sultana-core-motoko.did

@@ -1,8 +1,63 @@
+type WorkerRelationship = 
+ record {
+   salonId: SalonId;
+   workerIds: vec principal;
+ };
+type WorkerId = text;
+type WeeklyTemplate = 
+ record {
+   day: DayOfWeek;
+   mask: TimeMask;
+   salonId: SalonId;
+   workerId: principal;
+ };
+type VisitPayment = 
+ record {
+   amount: nat;
+   id: nat;
+   method: PaymentMethod;
+ };
+type VisitItem = 
+ record {
+   id: nat;
+   name: text;
+   performedById: principal;
+   price: nat;
+   salonServiceId: opt SalonServiceId;
+ };
+type VisitId = text;
+type Visit = 
+ record {
+   appointmentId: opt AppointmentId;
+   clientName: text;
+   createdAt: nat64;
+   createdById: principal;
+   currency: text;
+   customerId: opt principal;
+   id: VisitId;
+   items: vec VisitItem;
+   notes: text;
+   payments: vec VisitPayment;
+   salonId: SalonId;
+   updatedAt: nat64;
+   updatedById: principal;
+   version: nat;
+ };
 type UserProfile = 
  record {
    avatarUrl: opt text;
    id: principal;
    name: text;
+   whatsAppNumber: opt text;
+ };
+type UpdateVisitArgs = 
+ record {
+   clientName: text;
+   customerId: opt principal;
+   items: vec CreateVisitItemArgs;
+   notes: text;
+   payments: vec CreateVisitPaymentArgs;
+   visitId: VisitId;
  };
 type UpdateSalonServiceArgs = 
  record {
@@ -10,7 +65,7 @@ type UpdateSalonServiceArgs =
    duration: nat;
    name: text;
    price: nat;
-   serviceId: SalonServiceId;
+   salonServiceId: SalonServiceId;
    serviceTypeIds: vec ServiceTypeId;
    workerIds: vec principal;
  };
@@ -18,13 +73,7 @@ type UpdateProfileArgs =
  record {
    avatarUrl: opt text;
    name: text;
- };
-type ToggleWorkerCapabilityArgs = 
- record {
-   canPerform: bool;
-   salonId: SalonId;
-   salonServiceId: SalonServiceId;
-   workerId: principal;
+   whatsAppNumber: opt text;
  };
 type TimeMask = vec nat64;
 type SetWeeklyTemplateArgs = 
@@ -41,6 +90,14 @@ type SetDailyScheduleArgs =
    workerId: principal;
  };
 type ServiceTypeId = text;
+type SearchForSalonServicesArgs = 
+ record {
+   geohashes6: vec Geohash;
+   serviceTypeId: ServiceTypeId;
+   startTimeUTC: nat64;
+   targetCount: opt nat8;
+   timeOffset: int;
+ };
 type SalonServiceId = text;
 type SalonService = 
  record {
@@ -57,6 +114,11 @@ type SalonService =
    workerIds: vec principal;
  };
 type SalonId = text;
+type SalonCandidatesEntry = 
+ record {
+   candidateIds: vec principal;
+   salonId: SalonId;
+ };
 type Salon = 
  record {
    active: bool;
@@ -67,25 +129,31 @@ type Salon =
    name: text;
    ownerId: principal;
  };
+type Role = 
+ variant {
+   Customer;
+   Owner;
+   Worker;
+ };
 type Result_9 = 
  variant {
    err: Error;
-   ok: SalonId;
+   ok: vec ServiceTypeId;
  };
 type Result_8 = 
  variant {
    err: Error;
-   ok: TimeMask;
+   ok: Visit;
  };
 type Result_7 = 
  variant {
    err: Error;
-   ok: vec nat64;
+   ok: vec Visit;
  };
 type Result_6 = 
  variant {
    err: Error;
-   ok: vec Salon;
+   ok: vec UserProfile;
  };
 type Result_5 = 
  variant {
@@ -95,39 +163,98 @@ type Result_5 =
 type Result_4 = 
  variant {
    err: Error;
-   ok: vec UserProfile;
+   ok: nat;
  };
 type Result_3 = 
  variant {
    err: Error;
-   ok: vec ServiceTypeId;
+   ok: principal;
+ };
+type Result_21 = 
+ variant {
+   err: Error;
+   ok: SalonServiceId;
+ };
+type Result_20 = 
+ variant {
+   err: Error;
+   ok: AppointmentId;
  };
 type Result_2 = 
  variant {
    err: Error;
-   ok: principal;
+   ok: UserProfile;
+ };
+type Result_19 = 
+ variant {
+   err: Error;
+   ok: vec SalonServiceId;
+ };
+type Result_18 = 
+ variant {
+   err: Error;
+   ok: vec SalonId;
+ };
+type Result_17 = 
+ variant {
+   err: Error;
+   ok: SalonId;
+ };
+type Result_16 = 
+ variant {
+   err: Error;
+   ok: record {
+         customer: nat;
+         owner: nat;
+         worker: nat;
+       };
+ };
+type Result_15 = 
+ variant {
+   err: Error;
+   ok: vec Appointment;
+ };
+type Result_14 = 
+ variant {
+   err: Error;
+   ok: vec DailyScheduleEntry;
+ };
+type Result_13 = 
+ variant {
+   err: Error;
+   ok: vec nat64;
+ };
+type Result_12 = 
+ variant {
+   err: Error;
+   ok: TimeMask;
  };
 type Result_11 = 
  variant {
    err: Error;
-   ok: SalonServiceId;
+   ok: MigrationData;
  };
 type Result_10 = 
  variant {
    err: Error;
-   ok: AppointmentId;
+   ok: vec Salon;
  };
 type Result_1 = 
  variant {
    err: Error;
-   ok: UserProfile;
+   ok: bool;
  };
 type Result = 
  variant {
    err: Error;
-   ok;
+   ok: VisitId;
  };
 type RequestToJoinArgs = record {salonId: SalonId;};
+type RemoveWorkerFromSalonArgs = 
+ record {
+   salonId: SalonId;
+   workerId: principal;
+ };
 type RemoveDailyScheduleArgs = 
  record {
    date: nat64;
@@ -138,6 +265,47 @@ type RejectCandidateArgs =
    salonId: SalonId;
    workerId: principal;
  };
+type PaymentMethod = 
+ variant {
+   Card;
+   Cash;
+   Other: text;
+ };
+type MigrationQueryArgs = 
+ record {
+   entity: MigrationEntity;
+   from: nat;
+   to: nat;
+ };
+type MigrationEntity = 
+ variant {
+   Appointments;
+   SalonCandidates;
+   SalonServices;
+   Salons;
+   UserProfiles;
+   Visits;
+   WeeklyTemplates;
+   WorkerRelationships;
+ };
+type MigrationData = 
+ variant {
+   Appointments: vec Appointment;
+   SalonCandidates: vec SalonCandidatesEntry;
+   SalonServices: vec SalonService;
+   Salons: vec Salon;
+   UserProfiles: vec UserProfile;
+   Visits: vec Visit;
+   WeeklyTemplates: vec WeeklyTemplate;
+   WorkerRelationships: vec WorkerRelationship;
+ };
+type GetEffectiveMaskForSalonArgs = 
+ record {
+   date: nat64;
+   salonId: SalonId;
+   timeOffset: int;
+   workerId: principal;
+ };
 type GetDayFromWeeklyTemplateArgs = 
  record {
    day: DayOfWeek;
@@ -150,15 +318,55 @@ type GetDailyScheduleArgs =
    workerId: principal;
  };
 type Geohash = text;
-type Error = 
+type ErrorDetails = 
  variant {
    AlreadyExists;
+   InterCanisterConnectionError;
    InvalidData: text;
    NotAuthorized: text;
    NotFound;
+   RemoteCanisterError: text;
    ReturnsNull;
  };
+type Error = 
+ record {
+   details: ErrorDetails;
+   logsJson: text;
+ };
 type DayOfWeek = nat;
+type DailyScheduleRangeArgs = 
+ record {
+   fromDate: nat64;
+   toDate: nat64;
+ };
+type DailyScheduleEntry = 
+ record {
+   date: nat64;
+   mask: TimeMask;
+   workerId: principal;
+ };
+type CreateVisitPaymentArgs = 
+ record {
+   amount: nat;
+   method: PaymentMethod;
+ };
+type CreateVisitItemArgs = 
+ record {
+   name: text;
+   performedById: principal;
+   price: nat;
+   salonServiceId: opt SalonServiceId;
+ };
+type CreateVisitArgs = 
+ record {
+   appointmentId: opt AppointmentId;
+   clientName: opt text;
+   customerId: opt principal;
+   items: vec CreateVisitItemArgs;
+   notes: text;
+   payments: vec CreateVisitPaymentArgs;
+   salonId: SalonId;
+ };
 type CreateSalonArgs = 
  record {
    address: text;
@@ -171,17 +379,66 @@ type Coordinate =
    lat: float64;
    lng: float64;
  };
+type BulkSetWeeklyTemplatesArgs = 
+ record {
+   delegatedCaller: principal;
+   items: vec SetWeeklyTemplateArgs;
+ };
+type BulkRequestToJoinSalonsArgs = 
+ record {
+   delegatedCaller: principal;
+   salonIds: vec SalonId;
+ };
+type BulkCreateSalonsArgs = 
+ record {
+   delegatedCaller: principal;
+   items: vec CreateSalonArgs;
+ };
+type BulkAddSalonServicesArgs = 
+ record {
+   delegatedCaller: principal;
+   items: vec AddSalonServiceArgs;
+ };
+type BulkAcceptWorkersArgs = 
+ record {
+   delegatedCaller: principal;
+   items: vec AcceptWorkerArgs;
+ };
 type BookAppointmentArgs = 
  record {
-   dateMidnight: nat64;
-   dayOfWeek: DayOfWeek;
-   notes: opt text;
+   notes: text;
    salonId: SalonId;
    salonServiceId: SalonServiceId;
-   startTime: nat64;
+   startTimeUTC: nat64;
+   timeOffset: int;
    workerId: principal;
  };
+type AppointmentStatus = 
+ variant {
+   Cancelled;
+   Completed;
+   Confirmed;
+   NoShow;
+   Pending;
+ };
 type AppointmentId = text;
+type Appointment = 
+ record {
+   createdAt: nat64;
+   currency: text;
+   customerId: principal;
+   durationMinutes: nat;
+   id: AppointmentId;
+   lastUpdatedAt: nat64;
+   notes: text;
+   priceSnapshot: nat;
+   salonId: SalonId;
+   salonServiceId: SalonServiceId;
+   startTimeUTC: nat64;
+   status: AppointmentStatus;
+   timeOffset: int;
+   workerId: principal;
+ };
 type AddSalonServiceArgs = 
  record {
    active: bool;
@@ -192,6 +449,16 @@ type AddSalonServiceArgs =
    serviceTypeIds: vec ServiceTypeId;
    workerIds: vec principal;
  };
+type AddOrRemoveWorkerInSalonArgs = 
+ record {
+   salonServiceId: SalonServiceId;
+   workerId: WorkerId;
+ };
+type AddOrRemoveServiceTypeInSalonArgs = 
+ record {
+   salonServiceId: SalonServiceId;
+   serviceTypeId: ServiceTypeId;
+ };
 type AcceptWorkerArgs = 
  record {
    salonId: SalonId;
@@ -199,48 +466,80 @@ type AcceptWorkerArgs =
  };
 service : {
   /// Owner accepts a candidate into the team
-  acceptWorker: (args: AcceptWorkerArgs) -> (Result);
+  acceptWorker: (args: AcceptWorkerArgs) -> (Result_1);
   /// Adds a new service to a specific salon
-  addSalonService: (args: AddSalonServiceArgs) -> (Result_11);
-  addServiceType: (id: ServiceTypeId) -> (Result);
-  bookAppointment: (args: BookAppointmentArgs) -> (Result_10);
+  addSalonService: (args: AddSalonServiceArgs) -> (Result_21);
+  addServiceType: (id: ServiceTypeId) -> (Result_1);
+  addServiceTypeToSalonService: (args: AddOrRemoveServiceTypeInSalonArgs) ->
+   (Result_1);
+  addWorkerToSalonService: (args: AddOrRemoveWorkerInSalonArgs) -> (Result_1);
+  bookAppointment: (args: BookAppointmentArgs) -> (Result_20);
+  bulkAcceptWorkers: (args: BulkAcceptWorkersArgs) -> (Result_1);
+  bulkAddSalonServices: (args: BulkAddSalonServicesArgs) -> (Result_19);
+  bulkAddServiceTypes: (ids: vec ServiceTypeId) -> (Result_9);
+  bulkCreateSalons: (args: BulkCreateSalonsArgs) -> (Result_18);
+  bulkRequestToJoinSalons: (args: BulkRequestToJoinSalonsArgs) -> (Result_1);
+  bulkSetWeeklyTemplates: (args: BulkSetWeeklyTemplatesArgs) -> (Result_1);
+  clearLogs: () -> ();
   /// Creates a new salon and links it to the caller
-  createSalon: (args: CreateSalonArgs) -> (Result_9);
-  getAllProfiles: () -> (Result_4) query;
+  createSalon: (args: CreateSalonArgs) -> (Result_17);
+  createVisit: (args: CreateVisitArgs) -> (Result);
+  getActionQuotaLimits: () -> (Result_16) query;
+  getAllProfiles: () -> (Result_6) query;
+  getAppointmentsForCustomer: (customerId: principal) -> (Result_15) query;
+  /// Returns the list of profiles waiting for approval (Owner only)
+  getCandidatesBySalonId: (salonId: SalonId) -> (Result_6) query;
   /// Returns a specific daily override if it exists
-  getDailySchedule: (args: GetDailyScheduleArgs) -> (Result_8) query;
+  getDailySchedule: (args: GetDailyScheduleArgs) -> (Result_12) query;
+  /// Returns daily schedules with midnight timestamp in [fromDate, toDate] - for data migration to another canister
+  getDailySchedulesForMigration: (args: DailyScheduleRangeArgs) ->
+   (Result_14) query;
   getDayFromWeeklyTemplate: (args: GetDayFromWeeklyTemplateArgs) ->
-   (Result_7) query;
-  getMyProfile: () -> (Result_1) query;
-  /// Pobiera listę salonów aktualnie zalogowanego właściciela (używa indeksu)
-  getMySalons: () -> (Result_6) query;
-  /// Returns the list of profiles waiting for approval (Owner only)
-  getSalonCandidates: (salonId: SalonId) -> (Result_4) query;
-  /// Pobiera listę usług salonu na podstawie jego ID (widok dla właściciela)
+   (Result_13) query;
+  /// Returns the effective availability mask (daily override or weekly template fallback)
+  getEffectiveMaskForSalon: (args: GetEffectiveMaskForSalonArgs) ->
+   (Result_12) query;
+  /// Returns the highest migrationId for the given entity (= total number of records ever created)
+  getLastMigrationId: (entity: MigrationEntity) -> (Result_4) query;
+  getLogs: () -> (text) query;
+  /// Returns a page of migration data for the given entity and id range [from, to]
+  getMigrationData: (args: MigrationQueryArgs) -> (Result_11) query;
+  getMyProfile: () -> (Result_2) query;
+  /// Returns the list of salons owned by the currently logged-in owner (uses the index)
+  getMySalons: () -> (Result_10) query;
+  /// Returns the list of salon services by salon ID (owner view)
   getSalonServicesBySalonId: (salonId: SalonId) -> (Result_5) query;
-  /// Pobiera listę profili wszystkich pracowników zatrudnionych w danym salonie
-  getSalonWorkers: (salonId: SalonId) -> (Result_4) query;
-  getServiceTypes: () -> (Result_3) query;
-  getSystemAdmin: () -> (Result_2) query;
-  /// Właściciel odrzuca prośbę kandydata o dołączenie do zespołu
-  rejectCandidate: (args: RejectCandidateArgs) -> (Result);
-  removeDailySchedule: (args: RemoveDailyScheduleArgs) -> (Result);
+  getSalonsForWorker: () -> (Result_10) query;
+  getServiceTypes: () -> (Result_9) query;
+  getSystemAdmin: () -> (Result_3) query;
+  getVisit: (visitId: VisitId) -> (Result_8) query;
+  getVisitHistory: (visitId: VisitId) -> (Result_7) query;
+  getVisitsForSalon: (salonId: SalonId) -> (Result_7) query;
+  /// Returns the profiles of all workers employed at a given salon
+  getWorkersBySalonId: (salonId: SalonId) -> (Result_6) query;
+  /// Owner rejects a candidate's request to join the team
+  rejectCandidate: (args: RejectCandidateArgs) -> (Result_1);
+  removeDailySchedule: (args: RemoveDailyScheduleArgs) -> (Result_1);
   /// Permanently removes a salon service and cleans up search indexes
-  removeSalonService: (serviceId: SalonServiceId) -> (Result);
-  removeServiceType: (id: ServiceTypeId) -> (Result);
+  removeSalonServiceBySalonServiceId: (salonServiceId: SalonServiceId) ->
+   (Result_1);
+  removeServiceType: (id: ServiceTypeId) -> (Result_1);
+  removeServiceTypeFromSalonService: (args:
+   AddOrRemoveServiceTypeInSalonArgs) -> (Result_1);
   /// Owner removes a worker from the salon team
-  removeWorkerFromSalon: (salonId: SalonId, workerId: principal) -> (Result);
+  removeWorkerFromSalon: (args: RemoveWorkerFromSalonArgs) -> (Result_1);
+  removeWorkerFromSalonService: (args: AddOrRemoveWorkerInSalonArgs) ->
+   (Result_1);
   /// Worker sends a request to join a specific salon
-  requestToJoinSalon: (args: RequestToJoinArgs) -> (Result);
-  setDailySchedule: (args: SetDailyScheduleArgs) -> (Result);
-  /// Ustawia lub zmienia administratora systemu.
-  /// Jeśli admin nie jest ustawiony, pierwszy wywołujący staje się adminem.
-  /// Jeśli jest ustawiony, tylko obecny admin może przekazać uprawnienia komuś innemu.
-  setSystemAdmin: (newAdmin: opt principal) -> (Result_2);
-  setWeeklyTemplate: (args: SetWeeklyTemplateArgs) -> (Result);
-  /// Umożliwia właścicielowi salonu przypisanie lub odebranie uprawnień pracownikowi do wykonywania konkretnej usługi.
-  toggleWorkerCapability: (args: ToggleWorkerCapabilityArgs) -> (Result);
-  updateMyProfile: (args: UpdateProfileArgs) -> (Result_1);
+  requestToJoinSalon: (args: RequestToJoinArgs) -> (Result_1);
+  searchForSalonServices: (args: SearchForSalonServicesArgs) ->
+   (Result_5) query;
+  setActionQuotaLimit: (role: Role, newLimit: nat) -> (Result_4);
+  setDailySchedule: (args: SetDailyScheduleArgs) -> (Result_1);
+  setSystemAdmin: (newAdmin: opt principal) -> (Result_3);
+  setWeeklyTemplate: (args: SetWeeklyTemplateArgs) -> (Result_1);
+  updateMyProfile: (args: UpdateProfileArgs) -> (Result_2);
   /// Updates an existing service with new details and synchronizes the index
-  updateSalonService: (args: UpdateSalonServiceArgs) -> (Result);
+  updateSalonService: (args: UpdateSalonServiceArgs) -> (Result_1);
+  updateVisit: (args: UpdateVisitArgs) -> (Result);
 }