@mymehq/sdk 3.3.2 → 3.5.0

package/dist/index.d.ts

@@ -69,6 +69,21 @@ interface ClientConfig {
     cdnBaseUrl?: string;
 }
 interface UpdateOptions {
+    /**
+     * Version the caller expects the item to currently be at. When provided,
+     * the SDK skips the upfront `GET /items/:id` and PATCHes directly. If the
+     * server's actual version differs, the update 409s through the usual
+     * conflict path — the caller's retry policy is out of scope here.
+     *
+     * Prefer `expectedVersion` for bulk importers and sync loops that already
+     * know the version locally; one request instead of two.
+     */
+    expectedVersion?: number;
+    /**
+     * Legacy alias for `expectedVersion`. Kept for backwards compatibility;
+     * new code should use `expectedVersion`.
+     * @deprecated Use `expectedVersion`.
+     */
     version?: number;
     /**
      * Override the client's default conflict strategy for this update.
@@ -84,7 +99,10 @@ interface UpdateOptions {
     library?: boolean;
     /**
      * Item type. Required by the `auto` strategy when a `keep_both_copies`
-     * conflict spawns a sibling item. Omit to let the SDK pre-fetch it.
+     * conflict spawns a sibling item. Omit to let the SDK pre-fetch it —
+     * when `expectedVersion` is also omitted the pre-fetch happens upfront;
+     * when `expectedVersion` is provided the fetch is deferred until a
+     * `keep_both_copies` conflict actually needs it.
      */
     type?: string;
     /**
@@ -352,4 +370,56 @@ declare class ConflictError extends MymeError {
     constructor(current: ConflictSnapshot, ancestor: ConflictSnapshot, conflictingFields: string[], clientPatch: Record<string, unknown>);
 }
 
-export { type ClientConfig, type ConflictAutoMergeListener, type ConflictAutoMergedEvent, type ConflictData, ConflictError, type ConflictResolver, type ConflictStrategy, ForbiddenError, type ItemWithExtensions, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError };
+/**
+ * Reason a webhook signature did not validate. Receivers should treat
+ * any non-`valid` result as "do not trust this delivery".
+ *
+ * - `malformed` — the signature header was missing, empty, or not in
+ *   the `t=<unix>,v1=<hex>` form.
+ * - `too_old` — the parsed timestamp is outside the tolerance window
+ *   (default: more than 300s in the past, or more than 60s in the
+ *   future to allow for mild clock skew).
+ * - `mismatch` — the recomputed HMAC did not match the provided hex.
+ */
+type WebhookVerifyReason = "malformed" | "too_old" | "mismatch";
+interface WebhookVerifyResult {
+    valid: boolean;
+    reason?: WebhookVerifyReason;
+}
+interface VerifyWebhookSignatureInput {
+    /** The `X-Myme-Signature` header value as received. */
+    header: string | null | undefined;
+    /** The raw HTTP request body, exactly as received (pre-JSON-parse). */
+    rawBody: string;
+    /** The webhook secret shared with the Myme server. */
+    secret: string;
+    /**
+     * Maximum age (seconds in the past) to accept. Default 300 (5 min).
+     * Matches the documented platform contract.
+     */
+    tolerance?: number;
+    /**
+     * Maximum future skew (seconds) to tolerate. Default 60 — matches
+     * the documented platform contract. Timestamps further ahead than
+     * this are rejected as `too_old` (name is legacy; it captures
+     * "outside the acceptable window").
+     */
+    futureSkew?: number;
+    /**
+     * Injection point for tests. Defaults to `Date.now() / 1000`.
+     */
+    nowSeconds?: () => number;
+}
+/**
+ * Verify a webhook signature produced by the Myme server. The server
+ * emits `X-Myme-Signature: t=<unix>,v1=<hex-sha256>` where the HMAC
+ * signs `<timestamp>.<raw-body>`.
+ *
+ * Pass the raw body string exactly as received (before JSON.parse) and
+ * the same `secret` configured on the webhook. Returns a structured
+ * result so receivers can log the failure reason without retrying on
+ * a permanently-malformed payload.
+ */
+declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): WebhookVerifyResult;
+
+export { type ClientConfig, type ConflictAutoMergeListener, type ConflictAutoMergedEvent, type ConflictData, ConflictError, type ConflictResolver, type ConflictStrategy, ForbiddenError, type ItemWithExtensions, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError, type VerifyWebhookSignatureInput, type WebhookVerifyReason, type WebhookVerifyResult, verifyWebhookSignature };

package/dist/index.js

@@ -152,6 +152,13 @@ var HttpTransport = class {
 };
 
 // src/conflict.ts
+async function fetchItemType(transport, itemId) {
+  const res = await transport.request(
+    "GET",
+    `/items/${itemId}`
+  );
+  return res.item.type;
+}
 var MAX_RETRIES = 3;
 function isConflictResponse(body) {
   return typeof body === "object" && body !== null && "error" in body && "current" in body && "conflicting_fields" in body;
@@ -235,9 +242,10 @@ async function handleConflictUpdate(transport, itemId, itemType, clientPatch, ve
       const plan = planAutoMerge(conflict);
       let conflictedCopyId;
       if (plan.keepBothFields.length > 0) {
+        const effectiveType = itemType ?? await fetchItemType(transport, itemId);
         const sibling = await keepBothFlow(
           transport,
-          itemType,
+          effectiveType,
           result.current.properties,
           clientPatch,
           plan.keepBothFields
@@ -341,11 +349,14 @@ var MymeClient = class {
       );
     },
     update: async (id, properties, options) => {
-      let version = options?.version;
+      const expected = options?.expectedVersion ?? options?.version;
+      let version;
       let type = options?.type;
-      if (version === void 0 || type === void 0) {
+      if (expected !== void 0) {
+        version = expected;
+      } else {
         const item = await this.items.get(id);
-        version ??= item.version;
+        version = item.version;
         type ??= item.type;
       }
       const strategy = options?.conflict ?? this.defaultConflictStrategy;
@@ -760,6 +771,37 @@ var MymeClient = class {
     }
   }
 };
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var STRIPE_HEADER_RE = /^t=(\d+),v1=([0-9a-f]+)$/;
+function verifyWebhookSignature(input) {
+  const tolerance = input.tolerance ?? 300;
+  const futureSkew = input.futureSkew ?? 60;
+  const nowSeconds = input.nowSeconds ?? (() => Math.floor(Date.now() / 1e3));
+  const header = input.header?.trim() ?? "";
+  const match = STRIPE_HEADER_RE.exec(header);
+  if (!match?.[1] || !match[2]) {
+    return { valid: false, reason: "malformed" };
+  }
+  const timestamp = match[1];
+  const providedSig = match[2];
+  const ts = Number(timestamp);
+  const now = nowSeconds();
+  if (now - ts > tolerance || ts - now > futureSkew) {
+    return { valid: false, reason: "too_old" };
+  }
+  const computedSig = createHmac("sha256", input.secret).update(`${timestamp}.${input.rawBody}`).digest("hex");
+  if (computedSig.length !== providedSig.length) {
+    return { valid: false, reason: "mismatch" };
+  }
+  const computedBuf = Buffer.from(computedSig, "utf8");
+  const providedBuf = Buffer.from(providedSig, "utf8");
+  if (!timingSafeEqual(computedBuf, providedBuf)) {
+    return { valid: false, reason: "mismatch" };
+  }
+  return { valid: true };
+}
 export {
   ConflictError,
   ForbiddenError,
@@ -767,5 +809,6 @@ export {
   MymeError,
   NotFoundError,
   UnauthorizedError,
-  ValidationError
+  ValidationError,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mymehq/sdk",
-  "version": "3.3.2",
+  "version": "3.5.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@mymehq/shared": "3.3.2"
+    "@mymehq/shared": "3.4.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",