@nokinc-flur/sdk 1.1.0 → 1.1.1

package/dist/index.js

@@ -3482,13 +3482,419 @@ function createPartnerProfileAdminClient(opts) {
     }
   };
 }
+
+// src/artifacts/envelope.ts
+import { z as z15 } from "zod";
+var FLUR_ARTIFACT_URI_SCHEME = "flur";
+var FLUR_ARTIFACT_VERSION = 1;
+var FLUR_ARTIFACT_URI_PREFIX = `${FLUR_ARTIFACT_URI_SCHEME}://v${FLUR_ARTIFACT_VERSION}/`;
+var ArtifactTypeRe = /^[a-z][a-z0-9_]{1,63}$/;
+var ArtifactHeaderSchema = z15.object({
+  v: z15.literal(FLUR_ARTIFACT_VERSION),
+  t: z15.string().regex(ArtifactTypeRe, "invalid artifact type"),
+  iss: z15.string().min(1).max(128),
+  kid: z15.string().min(1).max(128),
+  iat: z15.number().int().nonnegative(),
+  exp: z15.number().int().positive().optional(),
+  nonce: z15.string().min(8).max(64).regex(/^[A-Za-z0-9_-]+$/, "nonce must be url-safe")
+});
+var FlurArtifactError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "FlurArtifactError";
+  }
+  code;
+};
+function base64UrlEncode(bytes) {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  const b64 = typeof btoa === "function" ? btoa(bin) : Buffer.from(bytes).toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(s) {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - s.length % 4);
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + pad;
+  if (typeof atob === "function") {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+function buildArtifactBody(input) {
+  if (!ArtifactTypeRe.test(input.type)) {
+    throw new FlurArtifactError(
+      `Invalid artifact type: ${input.type}`,
+      "INVALID_TYPE"
+    );
+  }
+  const iat = input.issuedAtSeconds ?? Math.floor(Date.now() / 1e3);
+  const header = {
+    v: FLUR_ARTIFACT_VERSION,
+    t: input.type,
+    iss: input.issuer,
+    kid: input.keyId,
+    iat,
+    ...input.expiresAtSeconds !== void 0 ? { exp: input.expiresAtSeconds } : {},
+    nonce: input.nonce
+  };
+  ArtifactHeaderSchema.parse(header);
+  return { ...header, data: input.data };
+}
+function signArtifact(body, privateKey) {
+  const sig = bytesToHex(sign(canonicalJSONBytes(body), privateKey));
+  return { body, sig };
+}
+function encodeArtifactUri(signed) {
+  const bodyBytes = canonicalJSONBytes(signed.body);
+  const bodyB64 = base64UrlEncode(bodyBytes);
+  const sigB64 = base64UrlEncode(hexToBytes(signed.sig));
+  return `${FLUR_ARTIFACT_URI_PREFIX}${signed.body.t}/${bodyB64}.${sigB64}`;
+}
+function decodeArtifactUri(uri) {
+  if (!uri.startsWith(FLUR_ARTIFACT_URI_PREFIX)) {
+    throw new FlurArtifactError(
+      `URI does not start with ${FLUR_ARTIFACT_URI_PREFIX}`,
+      "INVALID_URI"
+    );
+  }
+  const rest = uri.slice(FLUR_ARTIFACT_URI_PREFIX.length);
+  const slash = rest.indexOf("/");
+  if (slash <= 0) {
+    throw new FlurArtifactError("Missing artifact type segment", "INVALID_URI");
+  }
+  const type = rest.slice(0, slash);
+  const payload = rest.slice(slash + 1);
+  const dot = payload.indexOf(".");
+  if (dot <= 0 || dot === payload.length - 1) {
+    throw new FlurArtifactError(
+      "Missing body/signature separator",
+      "INVALID_URI"
+    );
+  }
+  if (!ArtifactTypeRe.test(type)) {
+    throw new FlurArtifactError(
+      `Invalid artifact type: ${type}`,
+      "INVALID_TYPE"
+    );
+  }
+  const bodyBytes = base64UrlDecode(payload.slice(0, dot));
+  const sigBytes = base64UrlDecode(payload.slice(dot + 1));
+  if (sigBytes.length !== 64) {
+    throw new FlurArtifactError(
+      `Signature must be 64 bytes, got ${sigBytes.length}`,
+      "INVALID_SIGNATURE"
+    );
+  }
+  let bodyJson;
+  try {
+    bodyJson = JSON.parse(new TextDecoder().decode(bodyBytes));
+  } catch {
+    throw new FlurArtifactError("Body is not valid JSON", "INVALID_BODY");
+  }
+  const headerOnly = ArtifactHeaderSchema.safeParse(bodyJson);
+  if (!headerOnly.success) {
+    throw new FlurArtifactError(
+      `Body header invalid: ${headerOnly.error.message}`,
+      "INVALID_BODY"
+    );
+  }
+  if (headerOnly.data.t !== type) {
+    throw new FlurArtifactError(
+      `URI type ${type} does not match body type ${headerOnly.data.t}`,
+      "TYPE_MISMATCH"
+    );
+  }
+  return {
+    type,
+    bodyBytes,
+    body: bodyJson,
+    sig: bytesToHex(sigBytes)
+  };
+}
+function verifyArtifactSignature(decoded, publicKey, options = {}) {
+  if (options.enforceExpiry !== false && decoded.body.exp !== void 0) {
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1e3);
+    if (decoded.body.exp < now) {
+      throw new FlurArtifactError("Artifact has expired", "EXPIRED");
+    }
+  }
+  return verify(decoded.bodyBytes, hexToBytes(decoded.sig), publicKey);
+}
+
+// src/artifacts/types.ts
+import { z as z16 } from "zod";
+var ARTIFACT_TYPES = {
+  OFFLINE_PAYMENT_AUTHORIZATION: "offline_payment_authorization",
+  RECEIPT: "receipt",
+  // --- stubs, schemas to be hardened in follow-ups ---
+  NQR_PAYMENT_REQUEST: "nqr_payment_request",
+  PAYMENT_INTENT: "payment_intent",
+  OFFLINE_CLAIM: "offline_claim",
+  SETTLEMENT_RECORD: "settlement_record",
+  REVERSAL_RECORD: "reversal_record",
+  LEDGER_JOURNAL_ENTRY: "ledger_journal_entry",
+  STATEMENT: "statement",
+  PASS: "pass",
+  IDENTITY: "identity"
+};
+var HexString4 = (length) => z16.string().regex(
+  new RegExp(`^[0-9a-fA-F]{${length * 2}}$`),
+  `expected ${length}-byte hex string`
+);
+var OfflinePaymentAuthorizationArtifactSchema = z16.object({
+  authorization: OfflinePaymentAuthorizationSchema
+});
+var ReceiptArtifactSchema = z16.object({
+  receiptId: z16.string().min(1).max(64),
+  paymentReference: z16.string().min(1).max(64),
+  payerUserId: z16.string().min(1).max(64).optional(),
+  payeeUserId: z16.string().min(1).max(64),
+  amountKobo: z16.number().int().positive(),
+  currency: z16.literal("NGN"),
+  channel: z16.enum(["online", "offline_reconciled", "pay_link", "nqr"]),
+  settledAtMs: z16.number().int().positive(),
+  ledgerTxnId: z16.string().min(1).max(64).optional(),
+  memo: z16.string().max(140).optional(),
+  hashChainPrev: HexString4(32).optional()
+});
+var ShortId = z16.string().min(1).max(64);
+var PositiveInt = z16.number().int().positive();
+var NonNegativeInt = z16.number().int().nonnegative();
+var Currency2 = z16.literal("NGN");
+var Memo = z16.string().max(140);
+var NqrPaymentRequestArtifactSchema = z16.object({
+  requestId: ShortId,
+  payeeUserId: ShortId,
+  amountKobo: PositiveInt.optional(),
+  currency: Currency2,
+  memo: Memo.optional(),
+  expiresAtMs: PositiveInt.optional()
+});
+var PaymentIntentArtifactSchema = z16.object({
+  intentId: ShortId,
+  payerUserId: ShortId,
+  payeeUserId: ShortId,
+  amountKobo: PositiveInt,
+  currency: Currency2,
+  idempotencyKey: ShortId,
+  createdAtMs: PositiveInt
+});
+var OfflineClaimArtifactSchema = z16.object({
+  claimId: ShortId,
+  authorizationId: ShortId,
+  payeeUserId: ShortId,
+  claimedAmountKobo: PositiveInt,
+  currency: Currency2,
+  claimedAtMs: PositiveInt,
+  paymentReference: ShortId.optional()
+});
+var SettlementRecordArtifactSchema = z16.object({
+  settlementId: ShortId,
+  ledgerTxnId: ShortId,
+  sourceRefType: z16.enum([
+    "offline_authorization",
+    "offline_claim",
+    "transfer",
+    "pay_link"
+  ]),
+  sourceRefId: ShortId,
+  amountKobo: PositiveInt,
+  currency: Currency2,
+  settledAtMs: PositiveInt
+});
+var ReversalRecordArtifactSchema = z16.object({
+  reversalId: ShortId,
+  originalTxnId: ShortId,
+  amountKobo: PositiveInt,
+  currency: Currency2,
+  reason: z16.enum([
+    "user_dispute",
+    "fraud",
+    "duplicate",
+    "admin_correction",
+    "other"
+  ]),
+  reversedAtMs: PositiveInt,
+  memo: Memo.optional()
+});
+var LedgerJournalEntryArtifactSchema = z16.object({
+  entryId: ShortId,
+  journalId: ShortId,
+  debitAccountId: ShortId,
+  creditAccountId: ShortId,
+  amountKobo: PositiveInt,
+  currency: Currency2,
+  postedAtMs: PositiveInt,
+  refType: ShortId.optional(),
+  refId: ShortId.optional()
+});
+var StatementArtifactSchema = z16.object({
+  statementId: ShortId,
+  userId: ShortId,
+  periodStartMs: PositiveInt,
+  periodEndMs: PositiveInt,
+  openingBalanceKobo: z16.number().int(),
+  closingBalanceKobo: z16.number().int(),
+  transactionCount: NonNegativeInt,
+  currency: Currency2,
+  hashChainPrev: HexString4(32).optional()
+}).refine((v) => v.periodEndMs > v.periodStartMs, {
+  message: "periodEndMs must be greater than periodStartMs",
+  path: ["periodEndMs"]
+});
+var PassArtifactSchema = z16.object({
+  passId: ShortId,
+  holderId: ShortId,
+  category: z16.enum(["membership", "ticket", "loyalty", "access", "voucher"]),
+  title: z16.string().min(1).max(120),
+  validFromMs: PositiveInt,
+  validUntilMs: PositiveInt.optional(),
+  metadata: z16.record(
+    z16.string().min(1).max(64),
+    z16.union([z16.string().max(280), z16.number(), z16.boolean()])
+  ).optional()
+}).refine(
+  (v) => v.validUntilMs === void 0 || v.validUntilMs > v.validFromMs,
+  {
+    message: "validUntilMs must be greater than validFromMs",
+    path: ["validUntilMs"]
+  }
+);
+var IdentityArtifactSchema = z16.object({
+  attestationId: ShortId,
+  subjectId: ShortId,
+  claimType: z16.enum([
+    "phone_verified",
+    "email_verified",
+    "bvn_verified",
+    "kyc_tier",
+    "age_band"
+  ]),
+  claimValueHash: HexString4(32),
+  attestedAtMs: PositiveInt
+});
+var ARTIFACT_BODY_SCHEMAS = {
+  [ARTIFACT_TYPES.OFFLINE_PAYMENT_AUTHORIZATION]: OfflinePaymentAuthorizationArtifactSchema,
+  [ARTIFACT_TYPES.RECEIPT]: ReceiptArtifactSchema,
+  [ARTIFACT_TYPES.NQR_PAYMENT_REQUEST]: NqrPaymentRequestArtifactSchema,
+  [ARTIFACT_TYPES.PAYMENT_INTENT]: PaymentIntentArtifactSchema,
+  [ARTIFACT_TYPES.OFFLINE_CLAIM]: OfflineClaimArtifactSchema,
+  [ARTIFACT_TYPES.SETTLEMENT_RECORD]: SettlementRecordArtifactSchema,
+  [ARTIFACT_TYPES.REVERSAL_RECORD]: ReversalRecordArtifactSchema,
+  [ARTIFACT_TYPES.LEDGER_JOURNAL_ENTRY]: LedgerJournalEntryArtifactSchema,
+  [ARTIFACT_TYPES.STATEMENT]: StatementArtifactSchema,
+  [ARTIFACT_TYPES.PASS]: PassArtifactSchema,
+  [ARTIFACT_TYPES.IDENTITY]: IdentityArtifactSchema
+};
+var HARDENED_ARTIFACT_TYPES = /* @__PURE__ */ new Set([
+  ARTIFACT_TYPES.OFFLINE_PAYMENT_AUTHORIZATION,
+  ARTIFACT_TYPES.RECEIPT,
+  ARTIFACT_TYPES.NQR_PAYMENT_REQUEST,
+  ARTIFACT_TYPES.PAYMENT_INTENT,
+  ARTIFACT_TYPES.OFFLINE_CLAIM,
+  ARTIFACT_TYPES.SETTLEMENT_RECORD,
+  ARTIFACT_TYPES.REVERSAL_RECORD,
+  ARTIFACT_TYPES.LEDGER_JOURNAL_ENTRY,
+  ARTIFACT_TYPES.STATEMENT,
+  ARTIFACT_TYPES.PASS,
+  ARTIFACT_TYPES.IDENTITY
+]);
+function isKnownArtifactType(t) {
+  return Object.values(ARTIFACT_TYPES).includes(t);
+}
+function isHardenedArtifactType(t) {
+  return HARDENED_ARTIFACT_TYPES.has(t);
+}
+
+// src/artifacts/codec.ts
+function createArtifactUri(input) {
+  if (!isKnownArtifactType(input.type)) {
+    throw new FlurArtifactError(
+      `Unknown artifact type: ${input.type}`,
+      "INVALID_TYPE"
+    );
+  }
+  if (!isHardenedArtifactType(input.type)) {
+    throw new FlurArtifactError(
+      `Artifact type ${input.type} is not yet hardened for emission`,
+      "INVALID_TYPE"
+    );
+  }
+  const schema = ARTIFACT_BODY_SCHEMAS[input.type];
+  const parsedData = schema.parse(input.data);
+  const body = buildArtifactBody({
+    type: input.type,
+    issuer: input.issuer,
+    keyId: input.keyId,
+    data: parsedData,
+    nonce: input.nonce,
+    issuedAtSeconds: input.issuedAtSeconds,
+    expiresAtSeconds: input.expiresAtSeconds
+  });
+  const signed = signArtifact(body, input.privateKey);
+  return { uri: encodeArtifactUri(signed), signed };
+}
+function verifyArtifactUri(uri, publicKey, options = {}) {
+  const decoded = decodeArtifactUri(uri);
+  if (!isKnownArtifactType(decoded.type)) {
+    throw new FlurArtifactError(
+      `Unknown artifact type: ${decoded.type}`,
+      "INVALID_TYPE"
+    );
+  }
+  if (!isHardenedArtifactType(decoded.type)) {
+    throw new FlurArtifactError(
+      `Artifact type ${decoded.type} is not yet hardened for verification`,
+      "INVALID_TYPE"
+    );
+  }
+  const schema = ARTIFACT_BODY_SCHEMAS[decoded.type];
+  const dataParsed = schema.safeParse(decoded.body.data);
+  if (!dataParsed.success) {
+    throw new FlurArtifactError(
+      `Artifact body invalid: ${dataParsed.error.message}`,
+      "INVALID_BODY"
+    );
+  }
+  const ok = verifyArtifactSignature(decoded, publicKey, options);
+  if (!ok) {
+    throw new FlurArtifactError(
+      "Artifact signature verification failed",
+      "INVALID_SIGNATURE"
+    );
+  }
+  return {
+    type: decoded.type,
+    body: decoded.body,
+    sig: decoded.sig,
+    decoded
+  };
+}
+function createReceiptArtifactUri(input) {
+  return createArtifactUri({
+    ...input,
+    type: ARTIFACT_TYPES.RECEIPT
+  });
+}
+function createOfflinePaymentAuthorizationArtifactUri(input) {
+  return createArtifactUri({
+    ...input,
+    type: ARTIFACT_TYPES.OFFLINE_PAYMENT_AUTHORIZATION
+  });
+}
 export {
   ACCOUNT_STATUSES,
   ACCOUNT_TYPES,
   ADDITIONAL_DATA_SUBFIELD,
+  ARTIFACT_BODY_SCHEMAS,
+  ARTIFACT_TYPES,
   AccountMembershipSchema,
   AccountSchema,
   ApiCredentialPublicSchema,
+  ArtifactHeaderSchema,
   COLLECTION_INTENT_STATUSES,
   COLLECTION_PAYMENT_STATUSES,
   CUSTODIAL_MODES,
@@ -3513,14 +3919,21 @@ export {
   EnableOfflineInputSchema,
   EnableOfflineResultSchema,
   FIELD,
+  FLUR_ARTIFACT_URI_PREFIX,
+  FLUR_ARTIFACT_URI_SCHEME,
+  FLUR_ARTIFACT_VERSION,
   FlurApiError,
+  FlurArtifactError,
   FlurCapExceededError,
   FlurClient,
   FlurError,
   FlurExpiredError,
   FlurReplayError,
+  HARDENED_ARTIFACT_TYPES,
+  IdentityArtifactSchema,
   IngestFundingResultSchema,
   IssueOACInputSchema,
+  LedgerJournalEntryArtifactSchema,
   ListPayoutDestinationsResultSchema,
   MEMBERSHIP_ROLES,
   MERCHANT_PAYOUT_STATUSES,
@@ -3531,11 +3944,14 @@ export {
   NGN_CURRENCY_CODE,
   NG_COUNTRY_CODE,
   NQRParseError,
+  NqrPaymentRequestArtifactSchema,
   OACSchema,
   OAC_DEFAULT_CUMULATIVE_KOBO,
   OAC_DEFAULT_PER_TX_KOBO,
   OAC_DEFAULT_VALIDITY_MS,
+  OfflineClaimArtifactSchema,
   OfflineHoldRecordSchema,
+  OfflinePaymentAuthorizationArtifactSchema,
   OfflinePaymentAuthorizationSchema,
   OfflinePaymentRequestSchema,
   OfflineStateResultSchema,
@@ -3554,10 +3970,12 @@ export {
   PartnerFundingEventInputSchema,
   PartnerFundingSchema,
   PartnerProfileSchema,
+  PassArtifactSchema,
   PassMetadataSchema,
   PassSchema,
   PayCollectionInputSchema,
   PaymentClaimSchema,
+  PaymentIntentArtifactSchema,
   PayoutDestinationSchema,
   PayoutEventInputSchema,
   ProviderEventInputSchema,
@@ -3566,22 +3984,29 @@ export {
   RECEIPT_CHANNELS,
   RECEIPT_KINDS,
   REPLAY_WINDOW_MS,
+  ReceiptArtifactSchema,
   ReceiptPayloadSchema,
   ReceiptSchema,
   ReconciliationReportSchema,
   RecordPayoutEventResultSchema,
   RedemptionSchema,
   RegisterDeviceKeyInputSchema,
+  ReversalRecordArtifactSchema,
   RevokeDeviceKeyInputSchema,
   SETTLEMENT_SCHEDULES,
   SettleResponseSchema,
+  SettlementRecordArtifactSchema,
   SettlementSchema,
   SignedConsumerOACSchema,
+  StatementArtifactSchema,
   UpsertMerchantProfileInputSchema,
   UpsertPartnerProfileInputSchema,
   WITHDRAWAL_STATES,
   WithdrawalSchema,
+  base64UrlDecode,
+  base64UrlEncode,
   bodySha256Hex,
+  buildArtifactBody,
   buildAuthorization,
   buildOAC,
   buildPass,
@@ -3597,21 +4022,26 @@ export {
   crc16ccittHex,
   createAccountsClient,
   createApiCredentialsAdminClient,
+  createArtifactUri,
   createCollectionsClient,
   createConsumerCollectionsClient,
   createConsumerWithdrawalsClient,
   createFlurPartnerClient,
   createHmacFetch,
   createMeOfflineClient,
+  createOfflinePaymentAuthorizationArtifactUri,
   createOfflineSettlementsClient,
   createPartnerCollectionsClient,
   createPartnerFundingClient,
   createPartnerProfileAdminClient,
   createPassesClient,
+  createReceiptArtifactUri,
   createReceiptsClient,
+  decodeArtifactUri,
   decodeAuthorizationQR,
   decodeBase45,
   decodePaymentRequestQR,
+  encodeArtifactUri,
   encodeAuthorizationQR,
   encodeBase45,
   encodeNQR,
@@ -3621,6 +4051,8 @@ export {
   generateKeyPair,
   generateStaticQR,
   init,
+  isHardenedArtifactType,
+  isKnownArtifactType,
   isPassWithinValidity,
   moneyMinorToNumber,
   normalizeE164,
@@ -3631,6 +4063,7 @@ export {
   readTLV,
   routingHint,
   sign,
+  signArtifact,
   signAuthorization,
   signCanonical,
   signOAC,
@@ -3641,6 +4074,8 @@ export {
   signRedemption,
   signRequestHMAC,
   verify,
+  verifyArtifactSignature,
+  verifyArtifactUri,
   verifyAuthorization,
   verifyCanonical,
   verifyOAC,