@molecule/api-resource-medication 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-resource-medication` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-resource-medication is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `@molecule/api-resource-medication` — medication tracking with
+ * dosing schedule + adherence log + adherence-rate calc.
+ *
+ * Owner-scoped: every medication and dose log belongs to the authenticated
+ * user. Medications carry dosage, `frequency` (e.g. `daily`, `twice_daily`),
+ * `times_of_day`, and active date range; dose logs record
+ * taken/skipped/late/missed and `adherenceRate` aggregates them over a date
+ * range.
+ *
+ * @example
+ * ```ts
+ * import { createMedicationRouter } from '@molecule/api-resource-medication'
+ * app.use('/medications', createMedicationRouter())
+ * // GET / · POST / · GET /adherence?from=…&to=… · GET|PUT|DELETE /:id
+ * // GET /:id/logs · POST /:id/logs
+ * ```
+ *
+ * @example
+ * ```ts
+ * import {
+ *   adherenceRate,
+ *   createMedicationForOwner,
+ *   logDose,
+ * } from '@molecule/api-resource-medication'
+ *
+ * const med = await createMedicationForOwner(userId, {
+ *   name: 'Metformin',
+ *   dosage: '500 mg',
+ *   frequency: 'twice_daily',
+ * })
+ * await logDose(med.id, userId, { status: 'taken' })
+ * const { rate } = await adherenceRate(userId, '2026-01-01', '2026-01-31')
+ * ```
+ *
+ * @remarks
+ * Tables: `src/__setup__/medications.sql` creates `medications` +
+ * `medication_logs`. An mlcl-scaffolded API replays `__setup__/*.sql`
+ * automatically on migrate; anywhere else run it once — nothing at runtime
+ * creates them.
+ *
+ * The router does not authenticate — it reads the caller from
+ * `res.locals.session` (populated by your global auth middleware) and 401s
+ * without a session. All service functions are `…ForOwner(…, ownerId)` and
+ * return `null` for rows the caller doesn't own — always pass the
+ * AUTHENTICATED user's id, never a client-sent one.
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one by
+ * one. This is HEALTH data: a box you can't check is a correctness or privacy
+ * bug to fix, never a skip:
+ * - [ ] Adding a medication persists its real fields — `name`, `dosage`,
+ *   `frequency`, `times_of_day` — and the med then appears in the user's list
+ *   (`GET /`) carrying those exact values, not a truncated or defaulted copy.
+ * - [ ] The schedule matches the frequency: a `twice_daily` med carries two
+ *   `times_of_day` entries and the UI shows two dose slots for the day — not one
+ *   and not three; a `daily` med shows exactly one. (Nothing derives the times
+ *   from `frequency` automatically, so a mismatch is a real bug to catch here.)
+ * - [ ] Logging a dose records it against the right medication and time:
+ *   `POST /:id/logs` with `status: 'taken'` (and its `taken_at`) then shows in
+ *   `GET /:id/logs`, and the adherence figure (`GET /adherence`) moves.
+ * - [ ] A skipped or missed dose is reflected HONESTLY — logged with
+ *   `status: 'missed'`/`'skipped'` it counts toward `total` but NOT `taken`, so
+ *   it lowers the adherence rate; it is never silently counted as taken (the
+ *   default status is `taken`, so a miss must be logged as a miss, not omitted).
+ * - [ ] CORRECTNESS — adherence is a true ratio of logged doses: a brand-new
+ *   med with zero logged doses reads 0% (`rate` 0, `total` 0), never 100%; a
+ *   partial day (some doses logged, some not yet) is never shown as complete.
+ * - [ ] If the app tracks refills/supply on top of this resource (the core does
+ *   not model one), recording a fill decrements the refills-remaining count and
+ *   a low-supply threshold raises a visible refill flag — verify both live.
+ * - [ ] PRIVACY/AUTHORIZATION — medication data is strictly per-user: signed in
+ *   as user B, guessing user A's medication id on `GET /:id`, `PUT /:id`,
+ *   `DELETE /:id`, or `/:id/logs` returns 404 (owner-scoped), never A's row; an
+ *   unauthenticated request 401s. Confirm PHI (name, dosage, notes) is never
+ *   written to server logs in the clear.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './routes.js';
+export * from './service.js';
+export * from './types.js';
+export * from './validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,85 @@
+/**
+ * `@molecule/api-resource-medication` — medication tracking with
+ * dosing schedule + adherence log + adherence-rate calc.
+ *
+ * Owner-scoped: every medication and dose log belongs to the authenticated
+ * user. Medications carry dosage, `frequency` (e.g. `daily`, `twice_daily`),
+ * `times_of_day`, and active date range; dose logs record
+ * taken/skipped/late/missed and `adherenceRate` aggregates them over a date
+ * range.
+ *
+ * @example
+ * ```ts
+ * import { createMedicationRouter } from '@molecule/api-resource-medication'
+ * app.use('/medications', createMedicationRouter())
+ * // GET / · POST / · GET /adherence?from=…&to=… · GET|PUT|DELETE /:id
+ * // GET /:id/logs · POST /:id/logs
+ * ```
+ *
+ * @example
+ * ```ts
+ * import {
+ *   adherenceRate,
+ *   createMedicationForOwner,
+ *   logDose,
+ * } from '@molecule/api-resource-medication'
+ *
+ * const med = await createMedicationForOwner(userId, {
+ *   name: 'Metformin',
+ *   dosage: '500 mg',
+ *   frequency: 'twice_daily',
+ * })
+ * await logDose(med.id, userId, { status: 'taken' })
+ * const { rate } = await adherenceRate(userId, '2026-01-01', '2026-01-31')
+ * ```
+ *
+ * @remarks
+ * Tables: `src/__setup__/medications.sql` creates `medications` +
+ * `medication_logs`. An mlcl-scaffolded API replays `__setup__/*.sql`
+ * automatically on migrate; anywhere else run it once — nothing at runtime
+ * creates them.
+ *
+ * The router does not authenticate — it reads the caller from
+ * `res.locals.session` (populated by your global auth middleware) and 401s
+ * without a session. All service functions are `…ForOwner(…, ownerId)` and
+ * return `null` for rows the caller doesn't own — always pass the
+ * AUTHENTICATED user's id, never a client-sent one.
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one by
+ * one. This is HEALTH data: a box you can't check is a correctness or privacy
+ * bug to fix, never a skip:
+ * - [ ] Adding a medication persists its real fields — `name`, `dosage`,
+ *   `frequency`, `times_of_day` — and the med then appears in the user's list
+ *   (`GET /`) carrying those exact values, not a truncated or defaulted copy.
+ * - [ ] The schedule matches the frequency: a `twice_daily` med carries two
+ *   `times_of_day` entries and the UI shows two dose slots for the day — not one
+ *   and not three; a `daily` med shows exactly one. (Nothing derives the times
+ *   from `frequency` automatically, so a mismatch is a real bug to catch here.)
+ * - [ ] Logging a dose records it against the right medication and time:
+ *   `POST /:id/logs` with `status: 'taken'` (and its `taken_at`) then shows in
+ *   `GET /:id/logs`, and the adherence figure (`GET /adherence`) moves.
+ * - [ ] A skipped or missed dose is reflected HONESTLY — logged with
+ *   `status: 'missed'`/`'skipped'` it counts toward `total` but NOT `taken`, so
+ *   it lowers the adherence rate; it is never silently counted as taken (the
+ *   default status is `taken`, so a miss must be logged as a miss, not omitted).
+ * - [ ] CORRECTNESS — adherence is a true ratio of logged doses: a brand-new
+ *   med with zero logged doses reads 0% (`rate` 0, `total` 0), never 100%; a
+ *   partial day (some doses logged, some not yet) is never shown as complete.
+ * - [ ] If the app tracks refills/supply on top of this resource (the core does
+ *   not model one), recording a fill decrements the refills-remaining count and
+ *   a low-supply threshold raises a visible refill flag — verify both live.
+ * - [ ] PRIVACY/AUTHORIZATION — medication data is strictly per-user: signed in
+ *   as user B, guessing user A's medication id on `GET /:id`, `PUT /:id`,
+ *   `DELETE /:id`, or `/:id/logs` returns 404 (owner-scoped), never A's row; an
+ *   unauthenticated request 401s. Confirm PHI (name, dosage, notes) is never
+ *   written to server logs in the clear.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './routes.js';
+export * from './service.js';
+export * from './types.js';
+export * from './validation.js';

package/dist/routes.d.ts

@@ -0,0 +1,4 @@
+import { Router } from 'express';
+/** Creates and returns the Express router for medication CRUD and dose-logging endpoints. */
+export declare function createMedicationRouter(): Router;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoD,MAAM,EAAE,MAAM,SAAS,CAAA;AAqBlF,6FAA6F;AAC7F,wBAAgB,sBAAsB,IAAI,MAAM,CAwG/C"}

package/dist/routes.js

@@ -0,0 +1,102 @@
+import { Router } from 'express';
+import { getParamId, requireUser } from '@molecule/api-bonds-default-express';
+import { t } from '@molecule/api-i18n';
+import { validateBody as validateBodyRaw } from '@molecule/api-middleware-validation';
+import { adherenceRate, createMedicationForOwner, deleteMedicationForOwner, getMedicationForOwner, listLogs, listMedicationsForOwner, logDose, updateMedicationForOwner, } from './service.js';
+import { logCreateSchema, medicationCreateSchema, medicationUpdateSchema } from './validation.js';
+const validateBody = validateBodyRaw;
+/** Creates and returns the Express router for medication CRUD and dose-logging endpoints. */
+export function createMedicationRouter() {
+    const router = Router();
+    router.get('/', async (_req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        res.json(await listMedicationsForOwner(userId, { include_inactive: true }));
+    });
+    router.post('/', validateBody(medicationCreateSchema), async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        res
+            .status(201)
+            .json(await createMedicationForOwner(userId, req.body));
+    });
+    router.get('/adherence', async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const from = req.query.from ?? new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+        const to = req.query.to ?? new Date().toISOString();
+        res.json(await adherenceRate(userId, from, to));
+    });
+    router.get('/:id', async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const m = await getMedicationForOwner(getParamId(req), userId);
+        if (!m) {
+            res.status(404).json({
+                error: t('medication.notFound', undefined, { defaultValue: 'Medication not found' }),
+            });
+            return;
+        }
+        res.json(m);
+    });
+    router.put('/:id', validateBody(medicationUpdateSchema), async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const m = await updateMedicationForOwner(getParamId(req), userId, req.body);
+        if (!m) {
+            res.status(404).json({
+                error: t('medication.notFound', undefined, { defaultValue: 'Medication not found' }),
+            });
+            return;
+        }
+        res.json(m);
+    });
+    router.delete('/:id', async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const ok = await deleteMedicationForOwner(getParamId(req), userId);
+        if (!ok) {
+            res.status(404).json({
+                error: t('medication.notFound', undefined, { defaultValue: 'Medication not found' }),
+            });
+            return;
+        }
+        res.status(204).end();
+    });
+    router.get('/:id/logs', async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const logs = await listLogs(getParamId(req), userId, {
+            from: typeof req.query.from === 'string' ? req.query.from : undefined,
+            to: typeof req.query.to === 'string' ? req.query.to : undefined,
+        });
+        if (logs === null) {
+            res.status(404).json({
+                error: t('medication.notFound', undefined, { defaultValue: 'Medication not found' }),
+            });
+            return;
+        }
+        res.json(logs);
+    });
+    router.post('/:id/logs', validateBody(logCreateSchema), async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const log = await logDose(getParamId(req), userId, req.body);
+        if (!log) {
+            res.status(404).json({
+                error: t('medication.notFound', undefined, { defaultValue: 'Medication not found' }),
+            });
+            return;
+        }
+        res.status(201).json(log);
+    });
+    return router;
+}

package/dist/service.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Medication-tracking service.
+ *
+ * @module
+ */
+import type { MedicationFrequency, MedicationLogRow, MedicationRow } from './types.js';
+/** Returns all medications belonging to the given owner, optionally including inactive ones. */
+export declare function listMedicationsForOwner(ownerId: string, opts?: {
+    include_inactive?: boolean;
+}): Promise<MedicationRow[]>;
+/** Fetches a single medication by ID, returning null if not found or not owned by the given owner. */
+export declare function getMedicationForOwner(medicationId: string, ownerId: string): Promise<MedicationRow | null>;
+/** Creates a new medication record owned by the given owner and returns the persisted row. */
+export declare function createMedicationForOwner(ownerId: string, data: {
+    name: string;
+    generic_name?: string | null;
+    dosage: string;
+    unit?: string | null;
+    frequency?: MedicationFrequency;
+    times_of_day?: string[];
+    start_date?: string | null;
+    end_date?: string | null;
+    notes?: string | null;
+}): Promise<MedicationRow>;
+/** Applies a partial patch to a medication, returning the updated row or null if not found or not owned. */
+export declare function updateMedicationForOwner(medicationId: string, ownerId: string, patch: Partial<MedicationRow>): Promise<MedicationRow | null>;
+/** Deletes a medication by ID, returning true on success or false if not found or not owned. */
+export declare function deleteMedicationForOwner(medicationId: string, ownerId: string): Promise<boolean>;
+/** Log a dose. If `status` not provided, infers from `taken_at` vs scheduled times. */
+export declare function logDose(medicationId: string, ownerId: string, data: {
+    taken_at?: string;
+    status?: 'taken' | 'skipped' | 'late' | 'missed';
+    notes?: string | null;
+}): Promise<MedicationLogRow | null>;
+/** Returns dose logs for a medication within an optional time window, or null if the medication is not found or not owned. */
+export declare function listLogs(medicationId: string, ownerId: string, opts?: {
+    from?: string;
+    to?: string;
+    limit?: number;
+}): Promise<MedicationLogRow[] | null>;
+/** Adherence summary: percentage of `taken` logs out of all logs in window. */
+export declare function adherenceRate(ownerId: string, from: string, to: string): Promise<{
+    taken: number;
+    total: number;
+    rate: number;
+}>;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAKtF,gGAAgG;AAChG,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,OAAO,CAAC,aAAa,EAAE,CAAC,CAK1B;AAED,sGAAsG;AACtG,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAI/B;AAED,8FAA8F;AAC9F,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,CAAC,EAAE,mBAAmB,CAAA;IAC/B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,GACA,OAAO,CAAC,aAAa,CAAC,CAexB;AAED,4GAA4G;AAC5G,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAK/B;AAED,gGAAgG;AAChG,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAKlB;AAED,uFAAuF;AACvF,wBAAsB,OAAO,CAC3B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;IAChD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,GACA,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAWlC;AAED,8HAA8H;AAC9H,wBAAsB,QAAQ,CAC5B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,gBAAgB,EAAE,GAAG,IAAI,CAAC,CAcpC;AAED,+EAA+E;AAC/E,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAYzD"}

package/dist/service.js

@@ -0,0 +1,103 @@
+/**
+ * Medication-tracking service.
+ *
+ * @module
+ */
+import { count, create, deleteById, findById, findMany, updateById, } from '@molecule/api-database';
+const MEDS_TABLE = 'medications';
+const LOGS_TABLE = 'medication_logs';
+/** Returns all medications belonging to the given owner, optionally including inactive ones. */
+export async function listMedicationsForOwner(ownerId, opts = {}) {
+    const where = [{ field: 'owner_id', operator: '=', value: ownerId }];
+    if (!opts.include_inactive)
+        where.push({ field: 'is_active', operator: '=', value: true });
+    const orderBy = [{ field: 'name', direction: 'asc' }];
+    return findMany(MEDS_TABLE, { where, orderBy });
+}
+/** Fetches a single medication by ID, returning null if not found or not owned by the given owner. */
+export async function getMedicationForOwner(medicationId, ownerId) {
+    const row = await findById(MEDS_TABLE, medicationId);
+    if (!row || row.owner_id !== ownerId)
+        return null;
+    return row;
+}
+/** Creates a new medication record owned by the given owner and returns the persisted row. */
+export async function createMedicationForOwner(ownerId, data) {
+    const result = await create(MEDS_TABLE, {
+        owner_id: ownerId,
+        name: data.name,
+        generic_name: data.generic_name ?? null,
+        dosage: data.dosage,
+        unit: data.unit ?? null,
+        frequency: data.frequency ?? 'daily',
+        times_of_day: data.times_of_day ?? [],
+        start_date: data.start_date ?? null,
+        end_date: data.end_date ?? null,
+        notes: data.notes ?? null,
+        is_active: true,
+    });
+    return result.data;
+}
+/** Applies a partial patch to a medication, returning the updated row or null if not found or not owned. */
+export async function updateMedicationForOwner(medicationId, ownerId, patch) {
+    const existing = await findById(MEDS_TABLE, medicationId);
+    if (!existing || existing.owner_id !== ownerId)
+        return null;
+    await updateById(MEDS_TABLE, medicationId, patch);
+    return findById(MEDS_TABLE, medicationId);
+}
+/** Deletes a medication by ID, returning true on success or false if not found or not owned. */
+export async function deleteMedicationForOwner(medicationId, ownerId) {
+    const row = await findById(MEDS_TABLE, medicationId);
+    if (!row || row.owner_id !== ownerId)
+        return false;
+    await deleteById(MEDS_TABLE, medicationId);
+    return true;
+}
+/** Log a dose. If `status` not provided, infers from `taken_at` vs scheduled times. */
+export async function logDose(medicationId, ownerId, data) {
+    const med = await getMedicationForOwner(medicationId, ownerId);
+    if (!med)
+        return null;
+    const result = await create(LOGS_TABLE, {
+        medication_id: medicationId,
+        owner_id: ownerId,
+        taken_at: data.taken_at ?? new Date().toISOString(),
+        status: data.status ?? 'taken',
+        notes: data.notes ?? null,
+    });
+    return result.data;
+}
+/** Returns dose logs for a medication within an optional time window, or null if the medication is not found or not owned. */
+export async function listLogs(medicationId, ownerId, opts = {}) {
+    const med = await getMedicationForOwner(medicationId, ownerId);
+    if (!med)
+        return null;
+    const where = [
+        { field: 'medication_id', operator: '=', value: medicationId },
+        { field: 'owner_id', operator: '=', value: ownerId },
+    ];
+    if (opts.from)
+        where.push({ field: 'taken_at', operator: '>=', value: opts.from });
+    if (opts.to)
+        where.push({ field: 'taken_at', operator: '<=', value: opts.to });
+    return findMany(LOGS_TABLE, {
+        where,
+        orderBy: [{ field: 'taken_at', direction: 'desc' }],
+        limit: opts.limit ?? 200,
+    });
+}
+/** Adherence summary: percentage of `taken` logs out of all logs in window. */
+export async function adherenceRate(ownerId, from, to) {
+    const where = [
+        { field: 'owner_id', operator: '=', value: ownerId },
+        { field: 'taken_at', operator: '>=', value: from },
+        { field: 'taken_at', operator: '<=', value: to },
+    ];
+    const total = await count(LOGS_TABLE, where);
+    const taken = await count(LOGS_TABLE, [
+        ...where,
+        { field: 'status', operator: '=', value: 'taken' },
+    ]);
+    return { taken, total, rate: total > 0 ? taken / total : 0 };
+}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Describes how often a medication is taken (e.g. daily, twice daily, as needed).
+ */
+export type MedicationFrequency = 'once' | 'daily' | 'twice_daily' | 'three_times_daily' | 'four_times_daily' | 'as_needed' | 'weekly' | 'custom';
+/**
+ * Database row shape for a medication record.
+ */
+export interface MedicationRow {
+    id: string;
+    owner_id: string;
+    name: string;
+    generic_name: string | null;
+    dosage: string;
+    unit: string | null;
+    frequency: MedicationFrequency;
+    times_of_day: string[];
+    start_date: string | Date | null;
+    end_date: string | Date | null;
+    notes: string | null;
+    is_active: boolean;
+    created_at: string | Date;
+    updated_at: string | Date;
+}
+/**
+ * Database row shape for a medication intake log entry.
+ */
+export interface MedicationLogRow {
+    id: string;
+    medication_id: string;
+    owner_id: string;
+    taken_at: string | Date;
+    status: 'taken' | 'skipped' | 'late' | 'missed';
+    notes: string | null;
+    created_at: string | Date;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,OAAO,GACP,aAAa,GACb,mBAAmB,GACnB,kBAAkB,GAClB,WAAW,GACX,QAAQ,GACR,QAAQ,CAAA;AAEZ;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,SAAS,EAAE,mBAAmB,CAAA;IAC9B,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;IAC/C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/** Valid dosing frequency options for a medication schedule. */
+export declare const MEDICATION_FREQUENCIES: readonly ["once", "daily", "twice_daily", "three_times_daily", "four_times_daily", "as_needed", "weekly", "custom"];
+/** Valid status values for a medication dose log entry. */
+export declare const LOG_STATUSES: readonly ["taken", "skipped", "late", "missed"];
+/** Zod schema for validating medication creation request payloads. */
+export declare const medicationCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    generic_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dosage: z.ZodString;
+    unit: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    frequency: z.ZodOptional<z.ZodEnum<{
+        once: "once";
+        daily: "daily";
+        twice_daily: "twice_daily";
+        three_times_daily: "three_times_daily";
+        four_times_daily: "four_times_daily";
+        as_needed: "as_needed";
+        weekly: "weekly";
+        custom: "custom";
+    }>>;
+    times_of_day: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    start_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    end_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Zod schema for validating medication update request payloads; all create fields become optional and `is_active` is added. */
+export declare const medicationUpdateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    generic_name: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    dosage: z.ZodOptional<z.ZodString>;
+    unit: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    frequency: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+        once: "once";
+        daily: "daily";
+        twice_daily: "twice_daily";
+        three_times_daily: "three_times_daily";
+        four_times_daily: "four_times_daily";
+        as_needed: "as_needed";
+        weekly: "weekly";
+        custom: "custom";
+    }>>>;
+    times_of_day: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    start_date: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    end_date: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    notes: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    is_active: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Zod schema for validating medication dose log creation request payloads. */
+export declare const logCreateSchema: z.ZodObject<{
+    taken_at: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        taken: "taken";
+        skipped: "skipped";
+        late: "late";
+        missed: "missed";
+    }>>;
+    notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,qHASzB,CAAA;AAEV,2DAA2D;AAC3D,eAAO,MAAM,YAAY,iDAAkD,CAAA;AAE3E,sEAAsE;AACtE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;iBAUjC,CAAA;AAEF,gIAAgI;AAChI,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;iBAEjC,CAAA;AAEF,+EAA+E;AAC/E,eAAO,MAAM,eAAe;;;;;;;;;iBAI1B,CAAA"}

package/dist/validation.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/** Valid dosing frequency options for a medication schedule. */
+export const MEDICATION_FREQUENCIES = [
+    'once',
+    'daily',
+    'twice_daily',
+    'three_times_daily',
+    'four_times_daily',
+    'as_needed',
+    'weekly',
+    'custom',
+];
+/** Valid status values for a medication dose log entry. */
+export const LOG_STATUSES = ['taken', 'skipped', 'late', 'missed'];
+/** Zod schema for validating medication creation request payloads. */
+export const medicationCreateSchema = z.object({
+    name: z.string().min(1).max(255),
+    generic_name: z.string().max(255).nullable().optional(),
+    dosage: z.string().min(1).max(80),
+    unit: z.string().max(40).nullable().optional(),
+    frequency: z.enum(MEDICATION_FREQUENCIES).optional(),
+    times_of_day: z.array(z.string().regex(/^\d{2}:\d{2}$/)).optional(),
+    start_date: z.string().nullable().optional(),
+    end_date: z.string().nullable().optional(),
+    notes: z.string().max(2000).nullable().optional(),
+});
+/** Zod schema for validating medication update request payloads; all create fields become optional and `is_active` is added. */
+export const medicationUpdateSchema = medicationCreateSchema.partial().extend({
+    is_active: z.boolean().optional(),
+});
+/** Zod schema for validating medication dose log creation request payloads. */
+export const logCreateSchema = z.object({
+    taken_at: z.string().optional(),
+    status: z.enum(LOG_STATUSES).optional(),
+    notes: z.string().max(2000).nullable().optional(),
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@molecule/api-resource-medication",
+  "version": "1.0.0",
+  "description": "Medication tracking + dosing schedule + adherence log",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "medication",
+    "health",
+    "adherence",
+    "resource"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "26.1.2",
+    "express": "5.2.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@molecule/api-bonds-default-express": "^1.0.0",
+    "@molecule/api-database": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0",
+    "@molecule/api-middleware-validation": "^1.0.0",
+    "express": "^5.0.0",
+    "zod": "^4.0.0"
+  }
+}