appstore-api-mcp 1.16.4 → 1.18.0

package/src/storekit.js

@@ -0,0 +1,136 @@
+// Minimal client for Apple's StoreKit-host APIs (api.storekit.apple.com),
+// used here for the Retention Messaging API. This is a DIFFERENT host, auth and
+// wire format from the App Store Connect JSON:API (see client.js):
+//   - host: api.storekit.apple.com (prod) / api.storekit-sandbox.apple.com
+//   - auth: ES256 JWT, App Store Server API style (aud "appstoreconnect-v1",
+//           plus a `bid` bundle-id claim) — typically an In-App Purchase key
+//   - body: plain JSON (NOT the data/type/attributes JSON:API envelope)
+//
+// The Retention Messaging API is access-gated (pre-release, per-app approval).
+// Without the entitlement, calls return 404 "doesn't have access to this API".
+
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { importPKCS8, SignJWT } from "jose";
+
+export const STOREKIT_HOSTS = {
+  production: "https://api.storekit.apple.com",
+  sandbox: "https://api.storekit-sandbox.apple.com",
+};
+
+export class StoreKitClient {
+  constructor({ keyId, issuerId, privateKey, privateKeyBase64, privateKeyPath, bundleId } = {}) {
+    this.keyId = keyId;
+    this.issuerId = issuerId;
+    this.defaultBundleId = bundleId || null;
+    this._pem =
+      privateKey ||
+      (privateKeyBase64 ? Buffer.from(privateKeyBase64, "base64").toString("utf8") : null) ||
+      (privateKeyPath ? readFileSync(privateKeyPath, "utf8") : null);
+  }
+
+  /** True when a key id, issuer id and private key are all present. */
+  configured() {
+    return !!(this.keyId && this.issuerId && this._pem);
+  }
+
+  async _token(bundleId) {
+    if (!this.configured())
+      throw new Error(
+        "Retention Messaging API is not configured. Set RETENTION_KEY_ID, RETENTION_ISSUER_ID and a key " +
+          "(RETENTION_PRIVATE_KEY_PATH / RETENTION_PRIVATE_KEY / RETENTION_PRIVATE_KEY_BASE64) — typically an " +
+          "In-App Purchase key — or let it reuse the ASC_* key. A per-app bundleId is also required.",
+      );
+    const bid = bundleId || this.defaultBundleId;
+    if (!bid)
+      throw new Error(
+        "bundleId is required for the Retention Messaging API (it goes in the JWT `bid` claim). Pass bundleId, or set RETENTION_BUNDLE_ID.",
+      );
+    const now = Math.floor(Date.now() / 1000);
+    const key = await importPKCS8(this._pem, "ES256");
+    return new SignJWT({ bid })
+      .setProtectedHeader({ alg: "ES256", kid: this.keyId, typ: "JWT" })
+      .setIssuedAt(now)
+      .setIssuer(this.issuerId)
+      .setExpirationTime(now + 19 * 60)
+      .setAudience("appstoreconnect-v1")
+      .sign(key);
+  }
+
+  /**
+   * Make a request against the StoreKit host. `path` starts with /inApps/...
+   * opts: { body, bundleId, sandbox }.
+   */
+  async request(method, path, { body, bundleId, sandbox } = {}) {
+    const host = sandbox ? STOREKIT_HOSTS.sandbox : STOREKIT_HOSTS.production;
+    const token = await this._token(bundleId);
+    const headers = { Authorization: `Bearer ${token}` };
+    let payload;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+    const res = await fetch(host + path, { method, headers, body: payload });
+    const text = await res.text();
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+    if (!res.ok) {
+      const detail = typeof data === "string" ? data : data ? JSON.stringify(data) : "";
+      const err = new Error(
+        `Retention Messaging API ${method} ${path} failed: ${res.status} ${res.statusText}${detail ? " — " + detail : ""}`,
+      );
+      err.status = res.status;
+      err.body = data;
+      throw err;
+    }
+    return data ?? { ok: true, status: res.status };
+  }
+}
+
+// ---- Pure helpers (unit-testable) ----
+
+// Apple's documented limits for a retention message.
+export const RETENTION_LIMITS = {
+  header: 66,
+  body: 144,
+  bulletPoints: 5,
+  bulletText: 66,
+  imageAltText: 150,
+};
+
+/**
+ * Validate the text of a retention message against Apple's limits. Returns an
+ * array of human-readable problems (empty = OK). Does not throw.
+ */
+export function validateRetentionMessage({ header, body, bulletPoints, image } = {}) {
+  const problems = [];
+  if (!header || !header.trim()) problems.push("header is required.");
+  else if (header.length > RETENTION_LIMITS.header)
+    problems.push(`header is ${header.length} chars; max is ${RETENTION_LIMITS.header}.`);
+  if (!body || !body.trim()) problems.push("body is required.");
+  else if (body.length > RETENTION_LIMITS.body)
+    problems.push(`body is ${body.length} chars; max is ${RETENTION_LIMITS.body}.`);
+  if (Array.isArray(bulletPoints)) {
+    if (bulletPoints.length > RETENTION_LIMITS.bulletPoints)
+      problems.push(`${bulletPoints.length} bullet points; max is ${RETENTION_LIMITS.bulletPoints}.`);
+    bulletPoints.forEach((b, i) => {
+      const t = typeof b === "string" ? b : b?.text;
+      if (t && t.length > RETENTION_LIMITS.bulletText)
+        problems.push(`bullet ${i + 1} is ${t.length} chars; max is ${RETENTION_LIMITS.bulletText}.`);
+    });
+  }
+  if (image && image.altText && image.altText.length > RETENTION_LIMITS.imageAltText)
+    problems.push(`image altText is ${image.altText.length} chars; max is ${RETENTION_LIMITS.imageAltText}.`);
+  return problems;
+}
+
+/** A fresh RFC-4122 v4 UUID for a message identifier. */
+export function newMessageId() {
+  return randomUUID();
+}