1'use strict';
2
3// Shopify never exposes a reusable gift-card code through this adapter. This module
4// therefore keeps cards out of Wix import files, gates every read against Shopify's exact count,
5// and derives the merchant's per-card cutover obligation from durable local evidence.
6
7const fsp = require('node:fs/promises');
8const path = require('node:path');
9const { upsertAdapterCoverageRows, writeJsonAtomic } = require

shopify-gift-cards.js on GitHub

(

'../../../lib/source-coverage.js'

);

const { ShopifyCliError } = require('./shopify-cli.js');

const GIFT_QUERY = 'gift-cards';

const GIFT_CODES_COVERAGE_ID = 'shopify:gift-card-codes';

const GIFT_READ_COVERAGE_ID = 'shopify:gift-cards';

const GIFT_ACTION_CODE = 'shopify-gift-card-codes-not-migrated';

const RAW_DISCOVERY_DIR = 'data/shopify-discovery';

const EXTRACT_DIR = 'data/source-extract';

const CUTOVER_DIR = 'data/shopify-cutover';

const CENSUS_FILE = `${RAW_DISCOVERY_DIR}/gift-card-census.json`;

const ACTIVITY_FILE = `${CUTOVER_DIR}/gift-card-activity.json`;

const REMEDY_FILE = `${CUTOVER_DIR}/gift-card-remedy.json`;

const OWED_CSV_FILE = `${CUTOVER_DIR}/gift-cards-owed.csv`;

const CLOSED_TEXT = 'Every owed gift card was replaced and its holder told, against the final read';

const COUNT_WAITS_MS = Object.freeze([2000, 4000]);

function decimal(value) {

if (typeof value !== 'string' || !/^\d+(?:\.\d+)?$/.test(value)) {

const error = new Error(`invalid plain decimal ${JSON.stringify(value)}`);

error.code = 'shopify_gift_card_amount_invalid';

throw error;

}

const [whole, fraction = ''] = value.split('.');

return { units: BigInt(`${whole}${fraction}`), scale: fraction.length };

}

function scaleTo(value, scale) {

return value.units * (10n ** BigInt(scale - value.scale));

}

function compareDecimals(left, right) {

const scale = Math.max(left.scale, right.scale);

const a = scaleTo(left, scale);

const b = scaleTo(right, scale);

return a === b ? 0 : (a < b ? -1 : 1);

}

function formatDecimal(units, scale) {

const negative = units < 0n;

let digits = String(negative ? -units : units);

if (scale) digits = digits.padStart(scale + 1, '0');

const value = scale ? `${digits.slice(0, -scale)}.${digits.slice(-scale)}` : digits;

return negative ? `-${value}` : value;

}

function sumMoney(rows) {

const totals = new Map();

for (const money of rows) {

if (!money || typeof money.currencyCode !== 'string' || !money.currencyCode) {

const error = new Error('gift-card money has no currencyCode');

error.code = 'shopify_gift_card_amount_invalid';

throw error;

}

const amount = decimal(money.amount);

const prior = totals.get(money.currencyCode);

if (!prior) totals.set(money.currencyCode, amount);

else {

const scale = Math.max(prior.scale, amount.scale);

totals.set(money.currencyCode, { units: scaleTo(prior, scale) + scaleTo(amount, scale), scale });

}

return Object.fromEntries([...totals.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([currency, total]) => [currency, formatDecimal(total.units, total.scale)]));

}

function isPositive(amount) {

return decimal(amount).units > 0n;

}

function sanitizeCard(card) {

if (!card || typeof card !== 'object' || typeof card.id !== 'string') {

const error = new Error('gift-card record has no id');

error.code = 'shopify_gift_card_amount_invalid';

throw error;

}

// Validate both money fields even though only balance decides what is owed.

decimal(card.balance && card.balance.amount);

decimal(card.initialValue && card.initialValue.amount);

if (!card.balance || typeof card.balance.currencyCode !== 'string' || !card.initialValue || typeof card.initialValue.currencyCode !== 'string') {

const error = new Error('gift-card money has no currencyCode');

error.code = 'shopify_gift_card_amount_invalid';

throw error;

}

return {

id: card.id,

lastCharacters: card.lastCharacters || null,

balance: { amount: card.balance.amount, currencyCode: card.balance.currencyCode },

initialValue: { amount: card.initialValue.amount, currencyCode: card.initialValue.currencyCode },

enabled: card.enabled === true,

expiresOn: card.expiresOn || null,

createdAt: card.createdAt || null,

};

}

function summarizeCards(cards) {

const sanitized = cards.map(sanitizeCard);

const owed = sanitized.filter((card) => isPositive(card.balance.amount));

return {

cards: sanitized,

owed,

cardCount: sanitized.length,

owedCount: owed.length,

owedBalance: sumMoney(owed.map((card) => card.balance)),

owedDisabledOrExpiredCount: owed.filter((card) => card.enabled === false || Boolean(card.expiresOn)).length,

};

}

function giftCodesCoverageRow(evidence = CENSUS_FILE) {

return {

coverageId: GIFT_CODES_COVERAGE_ID,

platform: 'shopify',

capability: 'commerce.gift-cards',

sourceEntity: 'gift-card-codes',

routes: ['gift-cards'],

reason: 'route-unsupported',

evidence: { artifact: evidence, pointer: 'every card is code-less; see owed counts and balances' },

recoverability: 'not-recoverable',

disposition: null,

};

}

function failedReadCoverageRow({ artifact, pointer, recoveryAction }) {

return {

coverageId: GIFT_READ_COVERAGE_ID,

platform: 'shopify',

capability: 'commerce.gift-cards',

sourceEntity: 'gift-cards',

routes: ['gift-cards'],

reason: 'capture-failed',

evidence: { artifact, pointer },

recoverability: 'import-operator',

recoveryAction,

disposition: null,

};

}

function errorsText(errors) {

return (errors || []).map((error) => String((error && error.message) || 'GraphQL error')).join('; ').slice(0, 500);

}

function transientError(error) {

if (!error) return false;

if (error instanceof ShopifyCliError && error.code === 'shopify_throttled') return true;

if (['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN'].includes(error.code)) return true;

return /\b(?:HTTP )?5\d\d\b|network|socket|timed? ?out|temporar/i.test(`${String(error.message || '')}\n${String(error.stderrTail || '')}`);

}

function transientGraphql(errors) {

return (errors || []).some((error) => {

const code = error && error.extensions && error.extensions.code;

return code === 'THROTTLED' || code === 'INTERNAL_SERVER_ERROR' || /temporar|throttl/i.test(String(error && error.message));

});

}

function countQuery(createdAt = null) {

const filter = createdAt ? `query: "created_at:<='${createdAt}'", ` : '';

return `query RpGiftCardsCount { giftCardsCount(${filter}limit: null) { count precision } }`;

}

async function readGiftCardCount(execute, { createdAt = null, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {

const call = typeof execute.once === 'function' ? execute.once.bind(execute) : execute;

let last;

for (let attempt = 0; attempt < 3; attempt += 1) {

try {

const result = await call(countQuery(createdAt));

if (result && Array.isArray(result.errors) && result.errors.length) {

last = { errors: result.errors };

if (transientGraphql(result.errors) && attempt < 2) { await sleep(COUNT_WAITS_MS[attempt]); continue; }

return { error: errorsText(result.errors), errors: result.errors };

}

const counted = result && result.data && result.data.giftCardsCount;

if (!counted || !Number.isInteger(counted.count)) return { error: 'the count read returned no integer count' };

return { count: counted.count, precision: counted.precision || null };

} catch (error) {

if (error instanceof ShopifyCliError && error.code === 'source_auth_expired') throw error;

last = { thrown: error };

if (transientError(error) && attempt < 2) { await sleep(COUNT_WAITS_MS[attempt]); continue; }

return { error: String(error.message || error), thrown: error };

}

return { error: last && last.thrown ? String(last.thrown.message || last.thrown) : errorsText(last && last.errors) };

}

async function writeNdjsonAtomic(file, rows) {

await fsp.mkdir(path.dirname(file), { recursive: true });

const temp = `${file}.${process.pid}.${Date.now()}.tmp`;

await fsp.writeFile(temp, rows.map((row) => `${JSON.stringify(row)}\n`).join(''), 'utf8');

await fsp.rename(temp, file);

}

function safeOperationId(operationId) {

return String(operationId || 'unknown').split('/').filter(Boolean).pop().replace(/[^A-Za-z0-9._-]/g, '_');

}

async function readJson(file, fallback = null) {

try { return JSON.parse(await fsp.readFile(file, 'utf8')); }

catch (error) { if (error.code === 'ENOENT') return fallback; throw error; }

}

async function coverageHasGiftCodes(projectDir) {

for (const rel of ['discovery/source-coverage.json', `${RAW_DISCOVERY_DIR}/source-coverage.json`]) {

const file = await readJson(path.join(projectDir, rel));

if (file && Array.isArray(file.rows) && file.rows.some((row) => row.coverageId === GIFT_CODES_COVERAGE_ID)) return true;

}

return false;

}

async function giftCardReassemble(context) {

let summary;

try {

const cards = [];

for await (const card of context.records) cards.push(card);

summary = summarizeCards(cards);

} catch (error) {

if (error.code === 'shopify_gift_card_amount_invalid') return { ok: false, errorCode: error.code, message: error.message, evidence: { valueClass: 'invalid decimal amount' } };

throw error;

}

const readCreatedAt = context.entry.createdAt;

const counted = await readGiftCardCount(context.execute, { createdAt: readCreatedAt, sleep: context.sleep });

const atOrBefore = summary.cards.filter((card) => Number.isFinite(Date.parse(card.createdAt)) && Date.parse(card.createdAt) <= Date.parse(readCreatedAt)).length;

if (counted.error || counted.precision !== 'EXACT') {

return { ok: false, errorCode: 'shopify_gift_card_count_inexact', message: counted.error || `Shopify returned count precision ${counted.precision || 'missing'}`, evidence: { precision: counted.precision || null, error: counted.error || null, received: atOrBefore } };

}

if (atOrBefore < counted.count) {

return { ok: false, errorCode: 'shopify_gift_card_count_short', message: `the gift-card read contains ${atOrBefore} card(s) created by ${readCreatedAt}, below Shopify's exact count ${counted.count}`, evidence: { expected: counted.count, received: atOrBefore, precision: counted.precision, readCreatedAt } };

}

const read = {

operationId: context.entry.operationId || null,

createdAt: readCreatedAt || null,

completedAt: context.entry.completedAt || null,

lineCount: context.lines,

exactCount: counted.count,

countPrecision: counted.precision,

};

const entryFields = {

giftCardCount: summary.cardCount,

owedGiftCardCount: summary.owedCount,

owedGiftCardBalance: summary.owedBalance,

giftCardCountCheck: { expected: counted.count, received: atOrBefore, precision: counted.precision, queryCreatedAt: readCreatedAt },

};

if (context.caller === 'census') {

const census = {

cardCount: summary.cardCount,

owedCount: summary.owedCount,

owedBalance: summary.owedBalance,

owedDisabledOrExpiredCount: summary.owedDisabledOrExpiredCount,

read,

};

await writeJsonAtomic(path.join(context.projectDir, CENSUS_FILE), census);

return { ok: true, records: [], result: census, entry: entryFields };

}

const cardsFile = `${EXTRACT_DIR}/gift-card-reads/${safeOperationId(context.entry.operationId)}.ndjson`;

await writeNdjsonAtomic(path.join(context.projectDir, cardsFile), summary.cards);

entryFields.cardsFile = cardsFile;

const response = { ok: true, records: summary.cards, outputFile: 'gift-cards-codeless.ndjson', entry: entryFields };

if (summary.cardCount > 0 && !(await coverageHasGiftCodes(context.projectDir))) {

const row = giftCodesCoverageRow(`${EXTRACT_DIR}/extract-manifest.json`);

const update = await upsertAdapterCoverageRows(context.projectDir, { adapter: 'shopify', rows: [row] });

response.stop = {

code: 'shopify_gift_card_codes_unreadable',

message: 'Shopify gift cards first appeared during the extract. Their reusable codes are unreadable; the coverage row was added and the run must return to mapping.',

details: { coverageId: row.coverageId, ...update },

};

}

return response;

}

async function giftCardFailedHandler(context) {

await fsp.rm(path.join(context.stagingDir, 'gift-cards.jsonl'), { force: true });

const artifact = context.caller === 'extract' ? `${EXTRACT_DIR}/extract-manifest.json` : `${RAW_DISCOVERY_DIR}/bulk-manifest.json`;

const evidence = context.entry.error && context.entry.error.evidence;

const pointer = `queries.gift-cards; ${context.entry.errorCode || 'unknown'}${evidence ? `; ${JSON.stringify(evidence)}` : ''}`;

const row = failedReadCoverageRow({

artifact,

pointer,

recoveryAction: context.caller === 'extract'

? 'Fix the count or amount read, then run shopify-extract.js --retry-failed.'

: 'The extract reads gift cards again with the same exact-count gate; fix source access before import.',

});

if (context.caller === 'extract') await upsertAdapterCoverageRows(context.projectDir, { adapter: 'shopify', rows: [row] });

return { handlerOutcome: { coverageId: row.coverageId, ...(context.caller === 'extract' ? {} : { row }) } };

}

function registerGiftCardHandlers(bulk) {

bulk.registerHandlers({

failed: { byQuery: { [GIFT_QUERY]: giftCardFailedHandler } },

reassemble: { [GIFT_QUERY]: giftCardReassemble },

});

}

async function giftCardCensusStep(ctx, bulk) {

const manifestPath = path.join(ctx.rawDir, 'bulk-manifest.json');

const existing = await readJson(manifestPath);

if (!existing) {

const initial = await readGiftCardCount(ctx.execute);

if (initial.error || initial.precision !== 'EXACT') {

return { rows: [failedReadCoverageRow({ artifact: `${RAW_DISCOVERY_DIR}/discovery-steps.json`, pointer: initial.error || `giftCardsCount precision ${initial.precision || 'missing'}`, recoveryAction: 'Fix the Shopify gift-card count read; the extract will read the cards again through its exact-count gate.' })] };

}

if (initial.count === 0) return { rows: [], count: 0, precision: 'EXACT' };

}

registerGiftCardHandlers(bulk);

const runner = bulk.createBulkRunner({

projectDir: ctx.projectDir,

store: ctx.store,

caller: 'census',

manifestPath,

stagingDir: path.join(ctx.rawDir, 'bulk-staging'),

queries: existing ? null : [{ name: GIFT_QUERY, entity: GIFT_QUERY, text: bulk.generateQueryText(GIFT_QUERY) }],

execute: ctx.execute,

now: () => Date.parse(ctx.now()),

progress: ctx.progress,

});

const result = await runner.run();

const entry = result.manifest && result.manifest.queries && result.manifest.queries[GIFT_QUERY];

if (entry && entry.state === 'done') {

return {

rows: entry.result && entry.result.cardCount > 0 ? [giftCodesCoverageRow()] : [],

census: entry.result || null,

};

}

const row = entry && entry.handlerOutcome && entry.handlerOutcome.row;

return { rows: [row || failedReadCoverageRow({ artifact: `${RAW_DISCOVERY_DIR}/bulk-manifest.json`, pointer: `queries.gift-cards state ${(entry && entry.state) || 'unknown'}`, recoveryAction: 'Fix source access before import; the extract reads gift cards again.' })] };

}

async function readNdjson(file) {

const text = await fsp.readFile(file, 'utf8');

return text.split('\n').filter(Boolean).map((line) => JSON.parse(line));

}

async function manifestFiles(projectDir) {

const dir = path.join(projectDir, EXTRACT_DIR);

let names = [];

try { names = await fsp.readdir(dir); } catch (error) { if (error.code !== 'ENOENT') throw error; }

return names.filter((name) => name === 'extract-manifest.json' || /^extract-manifest\..+\.json$/.test(name)).map((name) => path.join(dir, name));

}

async function giftCardReads(projectDir) {

const currentPath = path.join(projectDir, EXTRACT_DIR, 'extract-manifest.json');

const reads = [];

let currentManifest = null;

let currentRead = null;

let currentCardsFileMissing = false;

for (const file of await manifestFiles(projectDir)) {

const manifest = await readJson(file);

if (file === currentPath) currentManifest = manifest;

const entry = manifest && manifest.queries && manifest.queries[GIFT_QUERY];

if (!entry || entry.state !== 'done' || !entry.cardsFile || !Number.isFinite(Date.parse(entry.createdAt))) continue;

try {

const read = { entry, cards: await readNdjson(path.join(projectDir, entry.cardsFile)), manifestPath: file, current: file === currentPath };

reads.push(read);

if (read.current) currentRead = read;

} catch (error) {

if (error.code !== 'ENOENT') throw error;

if (file === currentPath) currentCardsFileMissing = true;

}

reads.sort((a, b) => Date.parse(a.entry.createdAt) - Date.parse(b.entry.createdAt));

return { latest: reads[reads.length - 1] || null, currentManifest, currentRead, currentCardsFileMissing, reads };

}

function replacementClears(card, replacement) {

if (!replacement || replacement.currency !== card.balance.currencyCode) return false;

try { return compareDecimals(decimal(replacement.replacementAmount), decimal(card.balance.amount)) >= 0; }

catch { return false; }

}

function dateInTimezone(now, timezone) {

const parts = new Intl.DateTimeFormat('en-CA', { timeZone: timezone || 'UTC', year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(now instanceof Date ? now : new Date(now));

const get = (type) => parts.find((part) => part.type === type).value;

return `${get('year')}-${get('month')}-${get('day')}`;

}

function balanceText(balance) {

const entries = Object.entries(balance);

return entries.length ? entries.map(([currency, amount]) => `${currency} ${amount}`).join(', ') : 'no positive balance';

}

async function hasGiftCodesRow(projectDir) {

return coverageHasGiftCodes(projectDir);

}

async function evaluateGiftCardCutover(projectDir, { now = new Date() } = {}) {

if (!(await hasGiftCodesRow(projectDir))) return { present: false, action: null, cutoverAction: null };

const { latest, currentManifest, currentRead, currentCardsFileMissing } = await giftCardReads(projectDir);

const activity = await readJson(path.join(projectDir, ACTIVITY_FILE));

const remedy = await readJson(path.join(projectDir, REMEDY_FILE), { replacements: [] });

const replacements = new Map(((remedy && remedy.replacements) || []).map((row) => [row.id, row]));

const latestSummary = latest ? summarizeCards(latest.cards) : { owed: [], owedCount: 0, owedBalance: {} };

const current = currentManifest && currentManifest.queries && currentManifest.queries[GIFT_QUERY];

const finalExists = Boolean(activity && Number.isFinite(Date.parse(activity.activityStoppedAt)) && currentRead && Date.parse(currentRead.entry.createdAt) > Date.parse(activity.activityStoppedAt));

let finalSummary = null;

if (finalExists) finalSummary = summarizeCards(currentRead.cards);

const owed = finalSummary ? finalSummary.owed : latestSummary.owed;

const uncleared = finalSummary ? owed.filter((card) => !replacementClears(card, replacements.get(card.id))) : owed;

if (finalSummary && uncleared.length === 0) return { present: true, closed: true, action: null, cutoverAction: CLOSED_TEXT, finalRead: current };

const balances = sumMoney(uncleared.map((card) => card.balance));

let actionText;

if (!latest) actionText = 'Gift-card read failed — see shopify:gift-cards. No balance can be treated as cleared.';

else if (!finalSummary) {

const missing = currentCardsFileMissing ? ' The current gift-card read file is missing, so it cannot be final.' : '';

actionText = `Awaiting the final gift-card read after activity stops; ${latestSummary.owedCount} card(s), ${balanceText(latestSummary.owedBalance)}, remain potentially owed.${missing}`;

}

else actionText = `Replace ${uncleared.length} Shopify gift card(s) and notify their holders; ${balanceText(balances)} remains owed.`;

if (remedy && remedy.keepRedeemingUntil) {

const today = dateInTimezone(now, remedy.ianaTimezone || 'UTC');

actionText += today > remedy.keepRedeemingUntil

? ` The keep-redeeming date ${remedy.keepRedeemingUntil} has passed; balances are still owed.`

: ` Shopify keeps redeeming until ${remedy.keepRedeemingUntil}; this does not clear the balances.`;

}

return {

present: true,

closed: false,

finalRead: finalSummary ? current : null,

latestRead: latest && latest.entry,

uncleared,

balances: finalSummary ? balances : latestSummary.owedBalance,

cutoverAction: actionText,

action: {

code: GIFT_ACTION_CODE,

severity: 'high',

action: actionText,

deadlineReason: 'outstanding gift-card balances are customer money',

entity: 'commerce.gift-cards',

affectedCount: finalSummary ? uncleared.length : latestSummary.owedCount,

},

};

}

module.exports = {

GIFT_QUERY,

GIFT_CODES_COVERAGE_ID,

GIFT_READ_COVERAGE_ID,

GIFT_ACTION_CODE,

CENSUS_FILE,

ACTIVITY_FILE,

REMEDY_FILE,

OWED_CSV_FILE,

CLOSED_TEXT,

COUNT_WAITS_MS,

decimal,

compareDecimals,

formatDecimal,

sumMoney,

isPositive,

sanitizeCard,

summarizeCards,

giftCodesCoverageRow,

failedReadCoverageRow,

countQuery,

readGiftCardCount,

giftCardReassemble,

giftCardFailedHandler,

registerGiftCardHandlers,

giftCardCensusStep,

readJson,

writeNdjsonAtomic,

readNdjson,

giftCardReads,

replacementClears,

dateInTimezone,

evaluateGiftCardCutover,

};