agrs-sequelize-sdk 1.4.59 → 1.4.60

package/models/PublicApiBatchItem.js

@@ -1,166 +1,166 @@
-module.exports = (sequelize, DataTypes) => {
-  // public_api_batch_items — one durable work row per campaign inside a bulk
-  // batch. This is the queue the bounded-concurrency poller claims from:
-  //   UPDATE public_api_batch_items
-  //      SET status='PROCESSING', lease_until = now() + interval 'N minutes'
-  //    WHERE id IN (SELECT id FROM public_api_batch_items
-  //                  WHERE status='PENDING' ORDER BY created_at
-  //                  LIMIT :n FOR UPDATE SKIP LOCKED)
-  //   RETURNING id;
-  // The claim is admission control (exactly-once START across N instances), NOT
-  // mutual exclusion across the multi-minute FB round-trip — that is what
-  // `lease_until` + the in-core 0-ad / 0-campaign rechecks guard (R1/R2).
-  const PublicApiBatchItem = sequelize.define(
-    "PublicApiBatchItem",
-    {
-      id: {
-        type: DataTypes.UUID,
-        primaryKey: true,
-        defaultValue: DataTypes.UUIDV4,
-      },
-      batch_id: {
-        // Parent public_api_batches.id (UUID). No hard DB FK constraint by
-        // design — matches the ai_campaign_queue precedent: this is a
-        // high-throughput work queue where per-row FK checks and sync-time
-        // create-ordering add cost/risk for no integrity we don't already get
-        // from the atomic batch+items TXN. Association below is for querying.
-        type: DataTypes.UUID,
-        allowNull: false,
-        field: "batch_id",
-      },
-      item_index: {
-        // Position of this campaign within the submitted batch, for ordered
-        // reporting in GET /processes/{batchId}.
-        type: DataTypes.INTEGER,
-        allowNull: true,
-        field: "item_index",
-      },
-      status: {
-        type: DataTypes.STRING(50),
-        allowNull: false,
-        defaultValue: "PENDING",
-        validate: {
-          isIn: [["PENDING", "PROCESSING", "COMPLETED", "FAILED"]],
-        },
-      },
-      payload: {
-        // The single-campaign creation payload consumed by
-        // createSingleCampaign(payload, { batchItemId }). Self-contained.
-        type: DataTypes.JSONB,
-        allowNull: false,
-      },
-      process_id: {
-        // Bridge to CampaignCreationLogV2.process_id (D5). Assigned when the
-        // core starts; GET /processes joins item -> V2 log via this.
-        type: DataTypes.UUID,
-        allowNull: true,
-        field: "process_id",
-      },
-      agrs_cid: {
-        // AGRS Campaign ID — used by LOOP1 dedup and as the reclaim idempotency
-        // anchor (R2). Indexed for the campaign-level existence recheck.
-        type: DataTypes.STRING(255),
-        allowNull: true,
-        field: "agrs_cid",
-      },
-      idempotency_token: {
-        // Campaign-level idempotency anchor keyed by AGRS_CID + country group
-        // (R2). Lets a reclaimed re-entry prove "this campaign was already
-        // POSTed to FB" without a from-scratch re-create. Forward-compat now,
-        // populated when the S3 recheck lands.
-        type: DataTypes.STRING(255),
-        allowNull: true,
-        field: "idempotency_token",
-      },
-      lease_until: {
-        // R1: the REAL lease. A claimed item is owned until this instant. The
-        // reclaim sweep only re-dispatches when lease_until < now() (window set
-        // STRICTLY greater than worst-case single-creation wall time, incl.
-        // 80004 backoffs). A worker that loses its lease must abort, not write.
-        type: DataTypes.DATE,
-        allowNull: true,
-        field: "lease_until",
-      },
-      heartbeat_at: {
-        // R1 (optional gate): last liveness ping from the owning worker, so a
-        // long-but-alive creation isn't reclaimed on bare wall-clock alone.
-        type: DataTypes.DATE,
-        allowNull: true,
-        field: "heartbeat_at",
-      },
-      retry_count: {
-        // D-FAILURE: capped requeue count. Poison (exceeds cap) -> terminal
-        // FAILED, never re-looped.
-        type: DataTypes.INTEGER,
-        allowNull: false,
-        defaultValue: 0,
-        field: "retry_count",
-      },
-      error_message: {
-        type: DataTypes.TEXT,
-        allowNull: true,
-        field: "error_message",
-      },
-      error_code: {
-        // Machine-readable terminal cause (FB subcode / PG code / classifier
-        // verdict) surfaced via GET /processes.
-        type: DataTypes.STRING(100),
-        allowNull: true,
-        field: "error_code",
-      },
-      facebook_campaign_id: {
-        type: DataTypes.STRING(255),
-        allowNull: true,
-        field: "facebook_campaign_id",
-      },
-      claimed_at: {
-        type: DataTypes.DATE,
-        allowNull: true,
-        field: "claimed_at",
-      },
-      created_at: {
-        type: DataTypes.DATE,
-        allowNull: false,
-        defaultValue: DataTypes.NOW,
-        field: "created_at",
-      },
-      updated_at: {
-        type: DataTypes.DATE,
-        allowNull: true,
-        field: "updated_at",
-      },
-      completed_at: {
-        type: DataTypes.DATE,
-        allowNull: true,
-        field: "completed_at",
-      },
-    },
-    {
-      tableName: "public_api_batch_items",
-      timestamps: false,
-      // Named explicitly: prod sync runs alter:false, so any index added later
-      // to this (by-then existing) table needs a migration targeting the name.
-      indexes: [
-        { name: "pabi_batch_id_idx", fields: ["batch_id"] },
-        { name: "pabi_status_idx", fields: ["status"] },
-        // Composite: the reconciler roll-up filters by (batch_id, status).
-        { name: "pabi_batch_id_status_idx", fields: ["batch_id", "status"] },
-        // The poller claim scans PENDING oldest-first: (status, created_at).
-        { name: "pabi_status_created_at_idx", fields: ["status", "created_at"] },
-        { name: "pabi_process_id_idx", fields: ["process_id"] },
-        { name: "pabi_agrs_cid_idx", fields: ["agrs_cid"] },
-        { name: "pabi_lease_until_idx", fields: ["lease_until"] },
-      ],
-    }
-  );
-
-  PublicApiBatchItem.associate = (models) => {
-    PublicApiBatchItem.belongsTo(models.PublicApiBatch, {
-      foreignKey: "batch_id",
-      targetKey: "id",
-      as: "batch",
-    });
-  };
-
-  return PublicApiBatchItem;
-};
+module.exports = (sequelize, DataTypes) => {
+  // public_api_batch_items — one durable work row per campaign inside a bulk
+  // batch. This is the queue the bounded-concurrency poller claims from:
+  //   UPDATE public_api_batch_items
+  //      SET status='PROCESSING', lease_until = now() + interval 'N minutes'
+  //    WHERE id IN (SELECT id FROM public_api_batch_items
+  //                  WHERE status='PENDING' ORDER BY created_at
+  //                  LIMIT :n FOR UPDATE SKIP LOCKED)
+  //   RETURNING id;
+  // The claim is admission control (exactly-once START across N instances), NOT
+  // mutual exclusion across the multi-minute FB round-trip — that is what
+  // `lease_until` + the in-core 0-ad / 0-campaign rechecks guard (R1/R2).
+  const PublicApiBatchItem = sequelize.define(
+    "PublicApiBatchItem",
+    {
+      id: {
+        type: DataTypes.UUID,
+        primaryKey: true,
+        defaultValue: DataTypes.UUIDV4,
+      },
+      batch_id: {
+        // Parent public_api_batches.id (UUID). No hard DB FK constraint by
+        // design — matches the ai_campaign_queue precedent: this is a
+        // high-throughput work queue where per-row FK checks and sync-time
+        // create-ordering add cost/risk for no integrity we don't already get
+        // from the atomic batch+items TXN. Association below is for querying.
+        type: DataTypes.UUID,
+        allowNull: false,
+        field: "batch_id",
+      },
+      item_index: {
+        // Position of this campaign within the submitted batch, for ordered
+        // reporting in GET /processes/{batchId}.
+        type: DataTypes.INTEGER,
+        allowNull: true,
+        field: "item_index",
+      },
+      status: {
+        type: DataTypes.STRING(50),
+        allowNull: false,
+        defaultValue: "PENDING",
+        validate: {
+          isIn: [["PENDING", "PROCESSING", "COMPLETED", "FAILED"]],
+        },
+      },
+      payload: {
+        // The single-campaign creation payload consumed by
+        // createSingleCampaign(payload, { batchItemId }). Self-contained.
+        type: DataTypes.JSONB,
+        allowNull: false,
+      },
+      process_id: {
+        // Bridge to CampaignCreationLogV2.process_id (D5). Assigned when the
+        // core starts; GET /processes joins item -> V2 log via this.
+        type: DataTypes.UUID,
+        allowNull: true,
+        field: "process_id",
+      },
+      agrs_cid: {
+        // AGRS Campaign ID — used by LOOP1 dedup and as the reclaim idempotency
+        // anchor (R2). Indexed for the campaign-level existence recheck.
+        type: DataTypes.STRING(255),
+        allowNull: true,
+        field: "agrs_cid",
+      },
+      idempotency_token: {
+        // Campaign-level idempotency anchor keyed by AGRS_CID + country group
+        // (R2). Lets a reclaimed re-entry prove "this campaign was already
+        // POSTed to FB" without a from-scratch re-create. Forward-compat now,
+        // populated when the S3 recheck lands.
+        type: DataTypes.STRING(255),
+        allowNull: true,
+        field: "idempotency_token",
+      },
+      lease_until: {
+        // R1: the REAL lease. A claimed item is owned until this instant. The
+        // reclaim sweep only re-dispatches when lease_until < now() (window set
+        // STRICTLY greater than worst-case single-creation wall time, incl.
+        // 80004 backoffs). A worker that loses its lease must abort, not write.
+        type: DataTypes.DATE,
+        allowNull: true,
+        field: "lease_until",
+      },
+      heartbeat_at: {
+        // R1 (optional gate): last liveness ping from the owning worker, so a
+        // long-but-alive creation isn't reclaimed on bare wall-clock alone.
+        type: DataTypes.DATE,
+        allowNull: true,
+        field: "heartbeat_at",
+      },
+      retry_count: {
+        // D-FAILURE: capped requeue count. Poison (exceeds cap) -> terminal
+        // FAILED, never re-looped.
+        type: DataTypes.INTEGER,
+        allowNull: false,
+        defaultValue: 0,
+        field: "retry_count",
+      },
+      error_message: {
+        type: DataTypes.TEXT,
+        allowNull: true,
+        field: "error_message",
+      },
+      error_code: {
+        // Machine-readable terminal cause (FB subcode / PG code / classifier
+        // verdict) surfaced via GET /processes.
+        type: DataTypes.STRING(100),
+        allowNull: true,
+        field: "error_code",
+      },
+      facebook_campaign_id: {
+        type: DataTypes.STRING(255),
+        allowNull: true,
+        field: "facebook_campaign_id",
+      },
+      claimed_at: {
+        type: DataTypes.DATE,
+        allowNull: true,
+        field: "claimed_at",
+      },
+      created_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+        defaultValue: DataTypes.NOW,
+        field: "created_at",
+      },
+      updated_at: {
+        type: DataTypes.DATE,
+        allowNull: true,
+        field: "updated_at",
+      },
+      completed_at: {
+        type: DataTypes.DATE,
+        allowNull: true,
+        field: "completed_at",
+      },
+    },
+    {
+      tableName: "public_api_batch_items",
+      timestamps: false,
+      // Named explicitly: prod sync runs alter:false, so any index added later
+      // to this (by-then existing) table needs a migration targeting the name.
+      indexes: [
+        { name: "pabi_batch_id_idx", fields: ["batch_id"] },
+        { name: "pabi_status_idx", fields: ["status"] },
+        // Composite: the reconciler roll-up filters by (batch_id, status).
+        { name: "pabi_batch_id_status_idx", fields: ["batch_id", "status"] },
+        // The poller claim scans PENDING oldest-first: (status, created_at).
+        { name: "pabi_status_created_at_idx", fields: ["status", "created_at"] },
+        { name: "pabi_process_id_idx", fields: ["process_id"] },
+        { name: "pabi_agrs_cid_idx", fields: ["agrs_cid"] },
+        { name: "pabi_lease_until_idx", fields: ["lease_until"] },
+      ],
+    }
+  );
+
+  PublicApiBatchItem.associate = (models) => {
+    PublicApiBatchItem.belongsTo(models.PublicApiBatch, {
+      foreignKey: "batch_id",
+      targetKey: "id",
+      as: "batch",
+    });
+  };
+
+  return PublicApiBatchItem;
+};

package/models/PublicApiIdempotencyCache.js

@@ -1,135 +1,135 @@
-module.exports = (sequelize, DataTypes) => {
-  const PublicApiIdempotencyCache = sequelize.define(
-    "PublicApiIdempotencyCache",
-    {
-      id: {
-        type: DataTypes.UUID,
-        defaultValue: DataTypes.UUIDV4,
-        primaryKey: true,
-      },
-      // Scope every cached response to the buyer's user. Two different
-      // buyers using the same Idempotency-Key value must NOT collide, so
-      // the uniqueness index below is (user_id, key), not (key) alone.
-      user_id: {
-        type: DataTypes.UUID,
-        allowNull: false,
-        references: {
-          model: "Users",
-          key: "id",
-        },
-      },
-      // Which specific token issued the original request. Useful for
-      // support/debug ("was it the same token retrying?") but not part
-      // of uniqueness — a buyer rotating tokens mid-retry should still
-      // hit the cached response.
-      token_id: {
-        type: DataTypes.UUID,
-        allowNull: true,
-        references: {
-          model: "ApiToken",
-          key: "id",
-        },
-      },
-      // Client-supplied Idempotency-Key header. Buyer controls the value;
-      // we just store it and dedupe on it.
-      key: {
-        type: DataTypes.STRING(255),
-        allowNull: false,
-      },
-      // SHA-256 hex of the canonicalized request body. Used to reject
-      // "same key + different body" (Stripe-style strict mode) with 422.
-      // Canonicalization = JSON.stringify with sorted keys, so field-order
-      // differences don't cause a false conflict.
-      request_hash: {
-        type: DataTypes.STRING(64),
-        allowNull: false,
-      },
-      // HTTP method + path recorded for debug + admin views. Not used for
-      // dedup logic — dedup is by (user_id, key). Different endpoints
-      // reusing the same key is a client bug we surface via debug, not
-      // silently accommodate.
-      method: {
-        type: DataTypes.STRING(10),
-        allowNull: false,
-      },
-      path: {
-        type: DataTypes.STRING,
-        allowNull: false,
-      },
-      // NULL while the original request is still in-flight. Set to the
-      // final HTTP status on completion. A row with status_code IS NULL
-      // that hasn't expired means "another instance is currently
-      // processing this key" → we return 409 idempotency_inflight to
-      // the second caller so they retry after a beat.
-      status_code: {
-        type: DataTypes.INTEGER,
-        allowNull: true,
-      },
-      // Cached response body — replayed verbatim on retry hit.
-      response_body: {
-        type: DataTypes.JSONB,
-        allowNull: true,
-      },
-      // Cached response headers we want to replay (e.g. X-Request-Id
-      // from the original, Location, etc). Optional — most replays are
-      // fine without.
-      response_headers: {
-        type: DataTypes.JSONB,
-        allowNull: true,
-      },
-      // Explicit expiry column so the TTL-sweep cron/pg_cron can
-      // `DELETE WHERE expires_at < NOW()` without computing from
-      // created_at. Defaults to created_at + 24h; controller sets this
-      // when inserting so we don't rely on a DB trigger.
-      expires_at: {
-        type: DataTypes.DATE,
-        allowNull: false,
-      },
-    },
-    {
-      tableName: "PublicApiIdempotencyCache",
-      indexes: [
-        // Primary lookup: (user_id, key). UNIQUE so Postgres resolves N
-        // concurrent claims atomically — the loser hits a unique violation,
-        // Sequelize's findOrCreate catches it, re-finds the winner's row, and
-        // returns created=false. That is what makes exactly ONE of the "9
-        // concurrent retries" execute the work while the rest get 409.
-        //
-        // THIS INDEX IS THE ENTIRE FEATURE. Without it every concurrent INSERT
-        // succeeds and every retry re-runs the operation. Verified in prod on
-        // 2026-07-12: index absent -> a 9-way burst gave 5 executions; index
-        // present (local) -> exactly 1.
-        //
-        // Named explicitly so the migration that backfills it on already-created
-        // tables targets the same index. sequelize.sync() runs with alter:false
-        // in prod (server.js gates it on DB_COLUMN_TYPE_UPDATE), so it creates
-        // the table but does NOT add indexes to a table that already exists.
-        {
-          name: "PublicApiIdempotencyCache_user_id_key_uniq",
-          unique: true,
-          fields: ["user_id", "key"],
-        },
-        // Sweep index — cron does `DELETE WHERE expires_at < NOW()`. Not
-        // partial (would need to update after every insert); regular
-        // btree is fine for the sweep pattern.
-        {
-          name: "PublicApiIdempotencyCache_expires_at_idx",
-          fields: ["expires_at"],
-        },
-      ],
-    }
-  );
-
-  PublicApiIdempotencyCache.associate = (models) => {
-    PublicApiIdempotencyCache.belongsTo(models.Users, {
-      foreignKey: "user_id",
-      as: "user",
-    });
-    PublicApiIdempotencyCache.belongsTo(models.ApiToken, {
-      foreignKey: "token_id",
-      as: "token",
-    });
-  };
-
-  return PublicApiIdempotencyCache;
-};
+module.exports = (sequelize, DataTypes) => {
+  const PublicApiIdempotencyCache = sequelize.define(
+    "PublicApiIdempotencyCache",
+    {
+      id: {
+        type: DataTypes.UUID,
+        defaultValue: DataTypes.UUIDV4,
+        primaryKey: true,
+      },
+      // Scope every cached response to the buyer's user. Two different
+      // buyers using the same Idempotency-Key value must NOT collide, so
+      // the uniqueness index below is (user_id, key), not (key) alone.
+      user_id: {
+        type: DataTypes.UUID,
+        allowNull: false,
+        references: {
+          model: "Users",
+          key: "id",
+        },
+      },
+      // Which specific token issued the original request. Useful for
+      // support/debug ("was it the same token retrying?") but not part
+      // of uniqueness — a buyer rotating tokens mid-retry should still
+      // hit the cached response.
+      token_id: {
+        type: DataTypes.UUID,
+        allowNull: true,
+        references: {
+          model: "ApiToken",
+          key: "id",
+        },
+      },
+      // Client-supplied Idempotency-Key header. Buyer controls the value;
+      // we just store it and dedupe on it.
+      key: {
+        type: DataTypes.STRING(255),
+        allowNull: false,
+      },
+      // SHA-256 hex of the canonicalized request body. Used to reject
+      // "same key + different body" (Stripe-style strict mode) with 422.
+      // Canonicalization = JSON.stringify with sorted keys, so field-order
+      // differences don't cause a false conflict.
+      request_hash: {
+        type: DataTypes.STRING(64),
+        allowNull: false,
+      },
+      // HTTP method + path recorded for debug + admin views. Not used for
+      // dedup logic — dedup is by (user_id, key). Different endpoints
+      // reusing the same key is a client bug we surface via debug, not
+      // silently accommodate.
+      method: {
+        type: DataTypes.STRING(10),
+        allowNull: false,
+      },
+      path: {
+        type: DataTypes.STRING,
+        allowNull: false,
+      },
+      // NULL while the original request is still in-flight. Set to the
+      // final HTTP status on completion. A row with status_code IS NULL
+      // that hasn't expired means "another instance is currently
+      // processing this key" → we return 409 idempotency_inflight to
+      // the second caller so they retry after a beat.
+      status_code: {
+        type: DataTypes.INTEGER,
+        allowNull: true,
+      },
+      // Cached response body — replayed verbatim on retry hit.
+      response_body: {
+        type: DataTypes.JSONB,
+        allowNull: true,
+      },
+      // Cached response headers we want to replay (e.g. X-Request-Id
+      // from the original, Location, etc). Optional — most replays are
+      // fine without.
+      response_headers: {
+        type: DataTypes.JSONB,
+        allowNull: true,
+      },
+      // Explicit expiry column so the TTL-sweep cron/pg_cron can
+      // `DELETE WHERE expires_at < NOW()` without computing from
+      // created_at. Defaults to created_at + 24h; controller sets this
+      // when inserting so we don't rely on a DB trigger.
+      expires_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+      },
+    },
+    {
+      tableName: "PublicApiIdempotencyCache",
+      indexes: [
+        // Primary lookup: (user_id, key). UNIQUE so Postgres resolves N
+        // concurrent claims atomically — the loser hits a unique violation,
+        // Sequelize's findOrCreate catches it, re-finds the winner's row, and
+        // returns created=false. That is what makes exactly ONE of the "9
+        // concurrent retries" execute the work while the rest get 409.
+        //
+        // THIS INDEX IS THE ENTIRE FEATURE. Without it every concurrent INSERT
+        // succeeds and every retry re-runs the operation. Verified in prod on
+        // 2026-07-12: index absent -> a 9-way burst gave 5 executions; index
+        // present (local) -> exactly 1.
+        //
+        // Named explicitly so the migration that backfills it on already-created
+        // tables targets the same index. sequelize.sync() runs with alter:false
+        // in prod (server.js gates it on DB_COLUMN_TYPE_UPDATE), so it creates
+        // the table but does NOT add indexes to a table that already exists.
+        {
+          name: "PublicApiIdempotencyCache_user_id_key_uniq",
+          unique: true,
+          fields: ["user_id", "key"],
+        },
+        // Sweep index — cron does `DELETE WHERE expires_at < NOW()`. Not
+        // partial (would need to update after every insert); regular
+        // btree is fine for the sweep pattern.
+        {
+          name: "PublicApiIdempotencyCache_expires_at_idx",
+          fields: ["expires_at"],
+        },
+      ],
+    }
+  );
+
+  PublicApiIdempotencyCache.associate = (models) => {
+    PublicApiIdempotencyCache.belongsTo(models.Users, {
+      foreignKey: "user_id",
+      as: "user",
+    });
+    PublicApiIdempotencyCache.belongsTo(models.ApiToken, {
+      foreignKey: "token_id",
+      as: "token",
+    });
+  };
+
+  return PublicApiIdempotencyCache;
+};