@ordinatio/scheduling 0.7.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -0
- package/package.json +1 -1
- package/prisma/migrations/20261119000000_gift_certificates/migration.sql +67 -0
- package/prisma/schema.prisma +56 -0
- package/dist/index.d.mts +0 -2835
- package/dist/index.d.ts +0 -2835
- package/dist/index.js +0 -6543
- package/dist/index.mjs +0 -6350
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.0 (prepared 2026-11-21)
|
|
4
|
+
|
|
5
|
+
- **A booking paid in full with a gift certificate needs no payment id.** `bookAppointment` used to refuse a paid appointment type with no `paymentId` (`SCHED_400`). It now also accepts one whose `paymentProvider` is `GIFT_PAYMENT_PROVIDER` (`'gift_certificate'`, exported): the caller has checked the certificate, and must spend it with `redeemGiftCertificate` on the new appointment. Any other provider name still needs a `paymentId`. Nothing else changes, and a host that never sets that provider sees no difference.
|
|
6
|
+
|
|
7
|
+
## 0.8.0 (prepared 2026-11-19)
|
|
8
|
+
|
|
9
|
+
- **New: gift certificates.** Two new tables, `GiftCertificate` and `GiftCertificateTransaction` (migration `20261119000000_gift_certificates`, or `20261119000000_scheduling_gift_certificates` in the host database package; apply it before using certificates). A certificate is prepaid value in whole cents with a 12-character code (an alphabet without look-alikes, drawn with a cryptographic generator, stored upper case without hyphens, shown in groups of four with `formatGiftCode`). `issueGiftCertificate(db, organizationId, { amountCents, currency?, expiresAt?, recipientName?, recipientEmail?, purchaserName?, purchaserEmail?, message?, paymentId?, notes? }, createdByUserId?)` makes one worth 100 to 1,000,000 cents; the caller cannot choose the code or the balance. `listGiftCertificates`, `getGiftCertificate` (with its history) and `voidGiftCertificate` are scoped to the business. `checkGiftCertificate(db, organizationId, code)` tells a code holder only the balance, currency, expiry and state (`ACTIVE`, `VOID`, `EXPIRED`, `USED_UP`), and answers null for a malformed, unknown or another business's code, so codes cannot be probed.
|
|
10
|
+
- **Spending is safe at the same moment.** `redeemGiftCertificate(db, organizationId, code, { maxCents, currency, appointmentId?, note? })` takes the smaller of the balance and `maxCents` (so a certificate worth more than the bill keeps the rest) and returns what it took, the balance left and the currency. `currency` is the currency of the bill: a certificate only pays a bill in its own (`SCHED_1708`). Every spend and every refund first takes the certificate's row lock (a write to it that also moves its ledger counter on by one), so the checks that read its history cannot be overtaken and each ledger line gets its own number; a void takes the same lock through its own update. The balance is then written only if it still holds the value that was read, as a last fence (`SCHED_1703`, nothing taken), with its ledger line in the same transaction. Spending a certificate twice on one appointment is refused (`SCHED_1707`) unless the first spend was given back in full. `restoreGiftCertificate(db, organizationId, certificateId, { amountCents, appointmentId?, note? })` gives money back for a cancelled or refunded booking: with an appointment, no more than was spent on it and not yet returned, so a repeated refund returns nothing more; without one, never above the issued amount. A void certificate takes nothing back, and so does one with a status this version does not know; an expired one does, and its expiry is not extended. A database CHECK keeps a balance between zero and the issued amount, and a unique index keeps ledger line numbers from repeating, whatever the application does. The functions run on the Prisma client or on the client a transaction callback receives; any other handle is refused (`SCHED_1711`), and an error from them must abort a transaction the caller opened.
|
|
11
|
+
- **The history is in order.** Each ledger line has a `seq` (1 is the issue; each change is one higher), assigned under the lock, so the history reads in the order the balance actually changed. `getGiftCertificate` returns the first 1000 lines in `seq` order, with `truncated: true` when there were more. New columns: `GiftCertificate.ledgerSeq` and `GiftCertificateTransaction.seq`.
|
|
12
|
+
- **A payment that is reported twice makes one certificate.** `paymentId` is unique within a business (`@@unique([organizationId, paymentId])`): issuing again with a `paymentId` already used, for the same amount and currency, returns the first certificate, including when two requests race; asking for a different amount or currency is `SCHED_1710`. `issueGiftCertificateOnce` returns `{ certificate, created }`, so a caller can tell a repeat from a new sale and not record or announce it twice; `issueGiftCertificate` returns just the certificate.
|
|
13
|
+
- **Request text is checked.** An appointment id, note or currency that is not plain, bounded text is `SCHED_1709`; ids that are not text are "not found" (`SCHED_1712`). Emails are stored lower-case.
|
|
14
|
+
- Errors `SCHED_1700` to `SCHED_1712`. Redemption is not yet wired into booking or payment, and this release adds no routes; those come with the API and widget releases. The two read functions that take a code are not rate limited here: the host must limit them.
|
|
15
|
+
|
|
3
16
|
## 0.7.0 (prepared 2026-11-18)
|
|
4
17
|
|
|
5
18
|
- **New: API keys, so an outside tool can act for one business.** A new table, `OrganizationApiKey` (`name`, `access`, a short `prefix`, `keyHash`, `createdByUserId`, `lastUsedAt`, `revokedAt`; migration `20261118000000_organization_api_keys`, or `20261118000000_scheduling_organization_api_keys` in the host database package; apply it before using keys). `createApiKey(db, organizationId, { name, access }, createdByUserId?)` returns `{ key, view }`: the secret (`osk_` and 43 characters) is in the result once and only its SHA-256 is stored. `access` is `READ` or `FULL`; a business may have 25 live keys (`SCHED_1601` beyond that; two requests at the same moment can pass the check together). `listApiKeys` never returns a hash, `revokeApiKey` answers whether it revoked a live key of that business, and `verifyApiKey(db, secret)` returns who a live key acts as or null (it never throws for a bad secret, and records "last used" at most every ten minutes without ever refusing a valid key if that write fails). A key whose stored access level is not `READ` or `FULL` is refused. Bad requests are `SCHED_1600` with every problem at once; a failed "last used" write is logged as `SCHED_1602`. Also exported: `validateApiKeyRequest`, `looksLikeApiKey`, `MAX_ACTIVE_API_KEYS`.
|
package/package.json
CHANGED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
-- CreateTable
|
|
2
|
+
CREATE TABLE "GiftCertificate" (
|
|
3
|
+
"id" TEXT NOT NULL,
|
|
4
|
+
"organizationId" TEXT NOT NULL,
|
|
5
|
+
"code" TEXT NOT NULL,
|
|
6
|
+
"status" TEXT NOT NULL DEFAULT 'ACTIVE',
|
|
7
|
+
"currency" TEXT NOT NULL DEFAULT 'usd',
|
|
8
|
+
"initialCents" INTEGER NOT NULL,
|
|
9
|
+
"balanceCents" INTEGER NOT NULL,
|
|
10
|
+
"ledgerSeq" INTEGER NOT NULL DEFAULT 0,
|
|
11
|
+
"expiresAt" TIMESTAMP(3),
|
|
12
|
+
"recipientName" TEXT,
|
|
13
|
+
"recipientEmail" TEXT,
|
|
14
|
+
"purchaserName" TEXT,
|
|
15
|
+
"purchaserEmail" TEXT,
|
|
16
|
+
"message" TEXT,
|
|
17
|
+
"notes" TEXT,
|
|
18
|
+
"paymentId" TEXT,
|
|
19
|
+
"createdByUserId" TEXT,
|
|
20
|
+
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
|
21
|
+
"updatedAt" TIMESTAMP(3) NOT NULL,
|
|
22
|
+
|
|
23
|
+
CONSTRAINT "GiftCertificate_pkey" PRIMARY KEY ("id"),
|
|
24
|
+
-- A balance can never go below nothing or above what the certificate was issued for, whatever the application does.
|
|
25
|
+
CONSTRAINT "GiftCertificate_balance_range" CHECK ("balanceCents" >= 0 AND "balanceCents" <= "initialCents")
|
|
26
|
+
);
|
|
27
|
+
|
|
28
|
+
-- CreateTable
|
|
29
|
+
CREATE TABLE "GiftCertificateTransaction" (
|
|
30
|
+
"id" TEXT NOT NULL,
|
|
31
|
+
"certificateId" TEXT NOT NULL,
|
|
32
|
+
"organizationId" TEXT NOT NULL,
|
|
33
|
+
"seq" INTEGER NOT NULL,
|
|
34
|
+
"type" TEXT NOT NULL,
|
|
35
|
+
"amountCents" INTEGER NOT NULL,
|
|
36
|
+
"balanceAfterCents" INTEGER NOT NULL,
|
|
37
|
+
"appointmentId" TEXT,
|
|
38
|
+
"note" TEXT,
|
|
39
|
+
"createdByUserId" TEXT,
|
|
40
|
+
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
|
41
|
+
|
|
42
|
+
CONSTRAINT "GiftCertificateTransaction_pkey" PRIMARY KEY ("id")
|
|
43
|
+
);
|
|
44
|
+
|
|
45
|
+
-- CreateIndex
|
|
46
|
+
CREATE UNIQUE INDEX "GiftCertificate_code_key" ON "GiftCertificate"("code");
|
|
47
|
+
|
|
48
|
+
-- CreateIndex
|
|
49
|
+
CREATE UNIQUE INDEX "GiftCertificate_organizationId_paymentId_key" ON "GiftCertificate"("organizationId", "paymentId");
|
|
50
|
+
|
|
51
|
+
-- CreateIndex
|
|
52
|
+
CREATE INDEX "GiftCertificate_organizationId_status_idx" ON "GiftCertificate"("organizationId", "status");
|
|
53
|
+
|
|
54
|
+
-- CreateIndex
|
|
55
|
+
CREATE UNIQUE INDEX "GiftCertificateTransaction_certificateId_seq_key" ON "GiftCertificateTransaction"("certificateId", "seq");
|
|
56
|
+
|
|
57
|
+
-- CreateIndex
|
|
58
|
+
CREATE INDEX "GiftCertificateTransaction_organizationId_idx" ON "GiftCertificateTransaction"("organizationId");
|
|
59
|
+
|
|
60
|
+
-- CreateIndex
|
|
61
|
+
CREATE INDEX "GiftCertificateTransaction_appointmentId_idx" ON "GiftCertificateTransaction"("appointmentId");
|
|
62
|
+
|
|
63
|
+
-- AddForeignKey
|
|
64
|
+
ALTER TABLE "GiftCertificate" ADD CONSTRAINT "GiftCertificate_organizationId_fkey" FOREIGN KEY ("organizationId") REFERENCES "Organization"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
|
65
|
+
|
|
66
|
+
-- AddForeignKey
|
|
67
|
+
ALTER TABLE "GiftCertificateTransaction" ADD CONSTRAINT "GiftCertificateTransaction_certificateId_fkey" FOREIGN KEY ("certificateId") REFERENCES "GiftCertificate"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
package/prisma/schema.prisma
CHANGED
|
@@ -38,6 +38,7 @@ model Organization {
|
|
|
38
38
|
brand OrganizationBrand?
|
|
39
39
|
textSettings OrganizationTextSettings?
|
|
40
40
|
apiKeys OrganizationApiKey[]
|
|
41
|
+
giftCertificates GiftCertificate[]
|
|
41
42
|
}
|
|
42
43
|
|
|
43
44
|
// ===== BEGIN SHARED SCHEDULING MODELS (copied verbatim into the host schema by packages/database/scripts/sync-scheduling-schema.ts) =====
|
|
@@ -576,6 +577,61 @@ model OrganizationApiKey {
|
|
|
576
577
|
@@index([organizationId])
|
|
577
578
|
}
|
|
578
579
|
|
|
580
|
+
/// Prepaid value a business sells or gives away. The balance moves only together with a GiftCertificateTransaction row.
|
|
581
|
+
model GiftCertificate {
|
|
582
|
+
id String @id @default(cuid())
|
|
583
|
+
organizationId String
|
|
584
|
+
organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
|
|
585
|
+
/// The code in its stored form: upper case, no hyphens. Unique across all businesses.
|
|
586
|
+
code String @unique
|
|
587
|
+
/// ACTIVE or VOID. "Expired" and "used up" follow from expiresAt and balanceCents.
|
|
588
|
+
status String @default("ACTIVE")
|
|
589
|
+
currency String @default("usd")
|
|
590
|
+
initialCents Int
|
|
591
|
+
balanceCents Int
|
|
592
|
+
/// The number of the newest ledger line. Every change takes the row lock by adding one, so line numbers never repeat or go backwards.
|
|
593
|
+
ledgerSeq Int @default(0)
|
|
594
|
+
expiresAt DateTime?
|
|
595
|
+
recipientName String?
|
|
596
|
+
recipientEmail String?
|
|
597
|
+
purchaserName String?
|
|
598
|
+
purchaserEmail String?
|
|
599
|
+
message String?
|
|
600
|
+
notes String?
|
|
601
|
+
/// The payment that bought it, when it was sold online. One certificate per payment in a business, so a repeated payment notice cannot make a second.
|
|
602
|
+
paymentId String?
|
|
603
|
+
createdByUserId String?
|
|
604
|
+
createdAt DateTime @default(now())
|
|
605
|
+
updatedAt DateTime @updatedAt
|
|
606
|
+
transactions GiftCertificateTransaction[]
|
|
607
|
+
|
|
608
|
+
@@unique([organizationId, paymentId])
|
|
609
|
+
@@index([organizationId, status])
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
/// One line of a certificate's history. Never edited; removed only when its certificate is.
|
|
613
|
+
model GiftCertificateTransaction {
|
|
614
|
+
id String @id @default(cuid())
|
|
615
|
+
certificateId String
|
|
616
|
+
certificate GiftCertificate @relation(fields: [certificateId], references: [id], onDelete: Cascade)
|
|
617
|
+
organizationId String
|
|
618
|
+
/// The line's place in the certificate's history, from GiftCertificate.ledgerSeq at the time it was written.
|
|
619
|
+
seq Int
|
|
620
|
+
/// ISSUE, REDEEM, RESTORE or VOID.
|
|
621
|
+
type String
|
|
622
|
+
/// Signed: positive adds to the balance, negative takes from it.
|
|
623
|
+
amountCents Int
|
|
624
|
+
balanceAfterCents Int
|
|
625
|
+
appointmentId String?
|
|
626
|
+
note String?
|
|
627
|
+
createdByUserId String?
|
|
628
|
+
createdAt DateTime @default(now())
|
|
629
|
+
|
|
630
|
+
@@unique([certificateId, seq])
|
|
631
|
+
@@index([organizationId])
|
|
632
|
+
@@index([appointmentId])
|
|
633
|
+
}
|
|
634
|
+
|
|
579
635
|
model ServicePackage {
|
|
580
636
|
id String @id @default(cuid())
|
|
581
637
|
name String
|