@xyo-network/rebilly-payment-card-authorization-plugin 2.94.1

package/dist/node/util/toTokenRequest.d.ts

@@ -0,0 +1,10 @@
+import { BillingAddress, PaymentCard } from '@xyo-network/payment-payload-plugins';
+import { CreatePaymentTokenRequest } from '../Api';
+/**
+ * Converts a payment card and billing address to a token request
+ * @param paymentCard The payment card
+ * @param billingAddress The billing address
+ * @returns The token request
+ */
+export declare const toTokenRequest: (paymentCard: PaymentCard, billingAddress: BillingAddress) => CreatePaymentTokenRequest;
+//# sourceMappingURL=toTokenRequest.d.ts.map

package/dist/node/util/toTokenRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toTokenRequest.d.ts","sourceRoot":"","sources":["../../../src/util/toTokenRequest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAA;AAElF,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAA;AAElD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,gBAAiB,WAAW,kBAAkB,cAAc,KAAG,yBAazF,CAAA"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@xyo-network/rebilly-payment-card-authorization-plugin",
+  "author": {
+    "email": "support@xyo.network",
+    "name": "XYO Development Team",
+    "url": "https://xyo.network"
+  },
+  "bugs": {
+    "email": "support@xyo.network",
+    "url": "https://github.com/XYOracleNetwork/plugins/issues"
+  },
+  "dependencies": {
+    "@xylabs/assert": "^3.1.11",
+    "@xylabs/axios": "^3.1.11",
+    "@xyo-network/id-payload-plugin": "^2.99.1",
+    "@xyo-network/module-model": "^2.99.1",
+    "@xyo-network/payload-builder": "^2.99.1",
+    "@xyo-network/payload-model": "^2.99.1",
+    "@xyo-network/payment-payload-plugins": "~2.94.1",
+    "@xyo-network/sentinel-abstract": "^2.99.1",
+    "@xyo-network/sentinel-model": "^2.99.1"
+  },
+  "devDependencies": {
+    "@xylabs/jest-helpers": "^3.1.11",
+    "@xylabs/ts-scripts-yarn3": "^3.9.1",
+    "@xylabs/tsconfig": "^3.9.1",
+    "@xyo-network/boundwitness-model": "^2.99.1",
+    "typescript": "^5.4.5"
+  },
+  "description": "Typescript/Javascript Plugins for XYO Platform",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "require": {
+          "types": "./dist/browser/index.d.cts",
+          "default": "./dist/browser/index.cjs"
+        },
+        "import": {
+          "types": "./dist/browser/index.d.mts",
+          "default": "./dist/browser/index.js"
+        }
+      },
+      "node": {
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        },
+        "import": {
+          "types": "./dist/node/index.d.mts",
+          "default": "./dist/node/index.js"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/node/index.cjs",
+  "module": "dist/node/index.js",
+  "homepage": "https://xyo.network",
+  "license": "LGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XYOracleNetwork/plugins.git"
+  },
+  "sideEffects": false,
+  "version": "2.94.1",
+  "type": "module"
+}

package/src/Api/PaymentCardToken/Request.ts

@@ -0,0 +1,238 @@
+export interface ContactPhoneNumber {
+  /**
+   * Phone number label or name.
+   * <= 45 characters
+   */
+  label: string
+  /**
+   * Specifies if the phone number is the contact's primary phone number.
+   */
+  primary?: boolean
+  /**
+   * Phone number value.
+   * <= 50 characters
+   */
+  value: string
+}
+
+export interface ContactEmail {
+  /**
+   * Email label or name.
+   * <= 45 characters
+   */
+  label: string
+  /**
+   * Specifies if the email address is the contact's primary email address.
+   */
+  primary?: boolean
+  /**
+   * Email address value.
+   * <= 255 characters
+   */
+  value: string
+}
+
+/**
+ * Billing address details associated with the payment token.
+ */
+export interface RequestBillingAddress {
+  /** Street address line 1. */
+  address: string
+  /** Street address line 2. */
+  address2?: string | null
+  /** City of the billing address. */
+  city?: string
+  /** Country code of the billing address, ISO 3166-1 alpha-2 code. */
+  country?: string
+  /** Date of birth of the cardholder. */
+  dob?: string
+  /** Email addresses associated with the billing address. */
+  emails?: ContactEmail[]
+  /** First name of the cardholder. */
+  firstName: string
+  /** Job title of the cardholder. */
+  jobTitle?: string | null
+  /** Last name of the cardholder. */
+  lastName: string
+  /** Organization or company name associated with the billing address. */
+  organization?: string | null
+  /** Phone numbers associated with the billing address. */
+  phoneNumbers?: ContactPhoneNumber[]
+  /** Postal or ZIP code of the billing address. */
+  postalCode?: string
+  /** State or region of the billing address. */
+  region?: string
+}
+
+export interface RequestPaymentCardInstrument {
+  /**
+   * Card Verification Value (CVV/CVC) of the payment card.
+   */
+  cvv: string
+  /**
+   * Expiration month of the payment card.
+   */
+  expMonth: number
+  /**
+   * Expiration year of the payment card.
+   */
+  expYear: number
+  /**
+   * Primary Account Number (PAN) of the payment card. This value is required to perform a payment.
+   */
+  pan: string
+}
+
+export type PaymentMethod =
+  // | 'ach'
+  // | 'AdvCash'
+  // | 'Alfa-click'
+  // | 'Alipay'
+  // | 'AstroPay Card'
+  // | 'AstroPay-GO'
+  // | 'Baloto'
+  // | 'Bancontact-mobile'
+  // | 'Bancontact'
+  // | 'bank-transfer-2'
+  // | 'bank-transfer-3'
+  // | 'bank-transfer-4'
+  // | 'bank-transfer-5'
+  // | 'bank-transfer-6'
+  // | 'bank-transfer-7'
+  // | 'bank-transfer-8'
+  // | 'bank-transfer-9'
+  // | 'bank-transfer'
+  // | 'BankReferenced'
+  // | 'Beeline'
+  // | 'Belfius-direct-net'
+  // | 'bitcoin'
+  // | 'Bizum'
+  // | 'Boleto'
+  // | 'cash-deposit'
+  // | 'cash'
+  // | 'CASHlib'
+  // | 'CashToCode'
+  // | 'check'
+  // | 'China UnionPay'
+  // | 'Cleo'
+  // | 'CODVoucher'
+  // | 'Conekta-oxxo'
+  // | 'cryptocurrency'
+  // | 'Cupon-de-pagos'
+  // | 'digital-wallet'
+  // | 'domestic-cards'
+  // | 'echeck'
+  // | 'ecoPayz'
+  // | 'ecoVoucher'
+  // | 'Efecty'
+  // | 'ePay.bg'
+  // | 'EPS'
+  // | 'eZeeWallet'
+  // | 'FasterPay'
+  // | 'Flexepin'
+  // | 'Giropay'
+  // | 'Google Pay'
+  // | 'Gpaysafe'
+  // | 'iDEAL'
+  // | 'iDebit'
+  // | 'ING-homepay'
+  // | 'INOVAPAY-pin'
+  // | 'INOVAPAY-wallet'
+  // | 'InstaDebit'
+  // | 'instant-bank-transfer'
+  // | 'InstantPayments'
+  // | 'Interac-eTransfer'
+  // | 'Interac-online'
+  // | 'Interac'
+  // | 'invoice'
+  // | 'iWallet'
+  // | 'Jeton'
+  // | 'jpay'
+  // | 'Khelocard'
+  // | 'Klarna'
+  // | 'KNOT'
+  // | 'loonie'
+  // | 'Matrix'
+  // | 'MaxiCash'
+  // | 'Megafon'
+  // | 'MiFinity-eWallet'
+  // | 'miscellaneous'
+  // | 'MTS'
+  // | 'MuchBetter'
+  // | 'Multibanco'
+  // | 'Neosurf'
+  // | 'Netbanking'
+  // | 'Neteller'
+  // | 'Nordea-Solo'
+  // | 'OchaPay'
+  // | 'online-bank-transfer'
+  // | 'Onlineueberweisen'
+  // | 'oriental-wallet'
+  // | 'OXXO'
+  // | 'P24'
+  // | 'Pagadito'
+  // | 'PagoEffectivo'
+  // | 'Pagsmile-deposit-express'
+  // | 'Pagsmile-lottery'
+  // | 'Pay4Fun'
+  // | 'PayCash'
+  // | 'Payeer'
+  'payment-card'
+// | 'PaymentAsia-crypto'
+// | 'Paymero'
+// | 'Paynote'
+// | 'paypal'
+// | 'Paysafecard'
+// | 'Paysafecash'
+// | 'PayTabs'
+// | 'Perfect-money'
+// | 'phone'
+// | 'PhonePe'
+// | 'Piastrix'
+// | 'PinPay'
+// | 'plaid-account'
+// | 'POLi'
+// | 'PostFinance-card'
+// | 'PostFinance-e-finance'
+// | 'QIWI'
+// | 'QPay'
+// | 'QQPay'
+// | 'rapyd-checkout'
+// | 'Resurs'
+// | 'SafetyPay'
+// | 'SEPA'
+// | 'Skrill Rapid Transfer'
+// | 'Skrill'
+// | 'SMSVoucher'
+// | 'Sofort'
+// | 'SparkPay'
+// | 'swift-dbt'
+// | 'Tele2'
+// | 'Terminaly-RF'
+// | 'ToditoCash-card'
+// | 'Trustly'
+// | 'UPayCard'
+// | 'UPI'
+// | 'USD-coin'
+// | 'VCreditos'
+// | 'VenusPoint'
+// | 'voucher-2'
+// | 'voucher-3'
+// | 'voucher-4'
+// | 'voucher'
+// | 'Webmoney'
+// | 'Webpay Card'
+// | 'Webpay-2'
+// | 'Webpay'
+// | 'WeChat Pay'
+// | 'XPay-P2P'
+// | 'XPay-QR'
+// | 'Yandex-money'
+// | 'Zimpler'
+// | 'Zotapay'
+
+export interface CreatePaymentTokenRequest {
+  billingAddress: RequestBillingAddress
+  method: PaymentMethod
+  paymentInstrument: RequestPaymentCardInstrument
+}

package/src/Api/PaymentCardToken/Response.ts

@@ -0,0 +1,73 @@
+import { PaymentMethod, RequestBillingAddress } from './Request'
+
+export interface ResponseBillingAddress extends RequestBillingAddress {
+  hash?: string | null
+}
+
+/**
+ * Main interface for API response encapsulating all relevant details.
+ */
+export interface CreateTokenResponse {
+  /** Hyperlinks to related API resources. */
+  _links: Link[]
+  /** Billing address associated with the payment token. */
+  billingAddress: ResponseBillingAddress
+  /** Card brand such as Visa or Mastercard. */
+  brand: string
+  /** An identifier for the browser data. */
+  browserData: unknown | null
+  /** Date and time when the token was created. */
+  createdTime: string
+  /** Expiration time of the token. */
+  expirationTime: string | null
+  /** Date and time when the token expired. */
+  expiredTime: string | null
+  /** An identifier for the fingerprint of the device used. */
+  fingerprint: string | null
+  /** An identifier of the token. */
+  id: string
+  /** Indicates if the token has been used. */
+  isUsed: boolean
+  /** The last four digits of the payment instrument. */
+  last4: string
+  /** Payment method such as 'payment-card'. */
+  method: PaymentMethod
+  /** Payment instrument details. */
+  paymentInstrument: ResponsePaymentCardInstrument
+  /** Metadata related to risk evaluation. */
+  riskMetadata: unknown | null
+  /** Date and time when the token was last updated. */
+  updatedTime: string
+  /** Usage time of the token. */
+  usageTime: string | null
+  /** Indicates if the token has already been used. */
+  used: boolean
+  /** Date and time when the token was first used. */
+  usedTime: string | null
+}
+
+/**
+ * Payment instrument details such as credit card information.
+ */
+export interface ResponsePaymentCardInstrument {
+  /** Bank identification number or issuer identification number of the card. */
+  bin: string
+  /** Card brand such as Visa or Mastercard. */
+  brand: string
+  /** Expiration month of the card. */
+  expMonth: number
+  /** Expiration year of the card. */
+  expYear: number
+  /** Last four digits of the card number. */
+  last4: string
+}
+
+/**
+ * Links structure for API navigation.
+ */
+export interface Link {
+  /** URL of the related resource. */
+  href: string
+  /** Relation type of the link. */
+  rel: string
+}

package/src/Api/PaymentCardToken/index.ts

@@ -0,0 +1,2 @@
+export * from './Request'
+export * from './Response'

package/src/Api/index.ts

@@ -0,0 +1 @@
+export * from './PaymentCardToken'

package/src/Config.ts

@@ -0,0 +1,18 @@
+import { SentinelConfig } from '@xyo-network/sentinel-model'
+
+import { RebillyApiDomainSettings } from './RebillyProviderSettings'
+import { RebillyPaymentCardAuthorizationSentinelSchema } from './Schema'
+
+export const RebillyPaymentCardAuthorizationSentinelConfigSchema = `${RebillyPaymentCardAuthorizationSentinelSchema}.config`
+export type RebillyPaymentCardAuthorizationSentinelConfigSchema = typeof RebillyPaymentCardAuthorizationSentinelConfigSchema
+
+/*
+ * The Rebilly Payment Card Authorization Sentinel Config
+ */
+export type RebillyPaymentCardAuthorizationSentinelConfig = SentinelConfig<{
+  /**
+   * The config schema
+   */
+  schema: RebillyPaymentCardAuthorizationSentinelConfigSchema
+}> &
+  Partial<RebillyApiDomainSettings>

package/src/Params.ts

@@ -0,0 +1,12 @@
+import { AnyConfigSchema } from '@xyo-network/module-model'
+import { SentinelParams } from '@xyo-network/sentinel-model'
+
+import { RebillyPaymentCardAuthorizationSentinelConfig } from './Config'
+import { RebillyOrganizationSettings, RebillyPublishableApiSettings } from './RebillyProviderSettings'
+
+export type RebillyPaymentCardAuthorizationParams = Partial<RebillyPublishableApiSettings & RebillyOrganizationSettings>
+
+export type RebillyPaymentCardAuthorizationSentinelParams<
+  TConfig extends AnyConfigSchema<RebillyPaymentCardAuthorizationSentinelConfig> = AnyConfigSchema<RebillyPaymentCardAuthorizationSentinelConfig>,
+  TParams extends RebillyPaymentCardAuthorizationParams = RebillyPaymentCardAuthorizationParams,
+> = SentinelParams<TConfig, TParams>

package/src/RebillyProviderSettings/RebillyApiSettings.ts

@@ -0,0 +1,23 @@
+export interface RebillyApiDomainSettings {
+  /**
+   * The Rebilly domain (https://api-sandbox.rebilly.com, https://api.rebilly.com)
+   */
+  domain: 'https://api-sandbox.rebilly.com' | 'https://api.rebilly.com'
+}
+
+export interface RebillyApiKeySettings extends RebillyApiDomainSettings {
+  /*
+   * The Rebilly API key
+   */
+  apiKey: string
+}
+export interface RebillyApiSettings extends RebillyApiDomainSettings, RebillyApiKeySettings {}
+
+export interface RebillyPublishableApiKeySettings extends RebillyApiDomainSettings {
+  /*
+   * The Rebilly Publishable API key
+   */
+  publishableApiKey: string
+}
+
+export interface RebillyPublishableApiSettings extends RebillyApiDomainSettings, RebillyPublishableApiKeySettings {}

package/src/RebillyProviderSettings/RebillyAuthSettings.ts

@@ -0,0 +1,15 @@
+export interface RebillyUserEmailSettings {
+  /**
+   * Email associated with Rebilly account
+   */
+  email: string
+}
+
+export interface RebillyUserPasswordSettings extends RebillyUserEmailSettings {
+  /**
+   * Password associated with Rebilly account
+   */
+  password: string
+}
+
+export interface RebillyAuthSettings extends RebillyUserEmailSettings, RebillyUserPasswordSettings {}

package/src/RebillyProviderSettings/RebillyOrganizationSettings.ts

@@ -0,0 +1,9 @@
+/**
+ * Rebilly organization settings
+ */
+export interface RebillyOrganizationSettings {
+  /**
+   * The Rebilly organization ID
+   */
+  organizationId: string
+}

package/src/RebillyProviderSettings/index.ts

@@ -0,0 +1,3 @@
+export * from './RebillyApiSettings'
+export * from './RebillyAuthSettings'
+export * from './RebillyOrganizationSettings'

package/src/Schema.ts

@@ -0,0 +1,2 @@
+export const RebillyPaymentCardAuthorizationSentinelSchema = 'network.xyo.sentinel.payments.payment.instrument.card.authorization.rebilly'
+export type RebillyPaymentCardAuthorizationSentinelSchema = typeof RebillyPaymentCardAuthorizationSentinelSchema

package/src/Sentinel.ts

@@ -0,0 +1,117 @@
+import { assertEx } from '@xylabs/assert'
+import { AxiosJson, AxiosRequestConfig, HttpStatusCode } from '@xylabs/axios'
+import { IdPayload, IdSchema } from '@xyo-network/id-payload-plugin'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import { Payload, WithSources } from '@xyo-network/payload-model'
+import { isBillingAddress, isPaymentCard } from '@xyo-network/payment-payload-plugins'
+import { AbstractSentinel } from '@xyo-network/sentinel-abstract'
+import { SentinelInstance, SentinelModuleEventData } from '@xyo-network/sentinel-model'
+
+import { CreateTokenResponse } from './Api'
+import { RebillyPaymentCardAuthorizationSentinelConfigSchema } from './Config'
+import { RebillyPaymentCardAuthorizationSentinelParams } from './Params'
+import { toTokenRequest } from './util'
+
+const removePrefix = (str: string, prefix: string) => {
+  const regex = new RegExp(`^${prefix}`)
+  return str.replace(regex, '')
+}
+
+const moduleName = 'RebillyPaymentCardAuthorizationSentinel'
+export class RebillyPaymentCardAuthorizationSentinel<
+  TParams extends RebillyPaymentCardAuthorizationSentinelParams = RebillyPaymentCardAuthorizationSentinelParams,
+  TEventData extends SentinelModuleEventData<SentinelInstance<TParams>> = SentinelModuleEventData<SentinelInstance<TParams>>,
+> extends AbstractSentinel<TParams, TEventData> {
+  static override configSchemas = [RebillyPaymentCardAuthorizationSentinelConfigSchema]
+  static override defaultConfigSchema = RebillyPaymentCardAuthorizationSentinelConfigSchema
+
+  protected _apiRoot: string | undefined = undefined
+  protected _domain: string | undefined = undefined
+  protected _headers: AxiosRequestConfig['headers'] | undefined = undefined
+  protected _organizationId: string | undefined = undefined
+  protected _publishableApiKey: string | undefined = undefined
+  protected _tokenEndpoint: string | undefined = undefined
+
+  /**
+   * The Rebilly Organization API root endpoint
+   */
+  protected get apiRoot() {
+    if (!this._apiRoot) this._apiRoot = `${this.domain}/organizations/${this.organizationId}`
+    return this._apiRoot
+  }
+
+  /**
+   * The Rebilly domain
+   */
+  protected get domain() {
+    if (!this._domain) this._domain = assertEx(this.params.domain ?? this.config.domain, () => `${moduleName}: Missing domain in params/config`)
+    return this._domain
+  }
+
+  /**
+   * The headers to be included in the request for each request
+   */
+  protected get headers(): AxiosRequestConfig['headers'] {
+    if (!this._headers) this._headers = { Authorization: this.publishableApiKey }
+    return this._headers
+  }
+
+  /**
+   * True if the environment is sandbox (testing), false otherwise
+   */
+  protected get isSandboxEnvironment(): boolean {
+    return this.domain.includes('sandbox')
+  }
+
+  /**
+   * The Rebilly organization ID
+   */
+  protected get organizationId() {
+    if (!this._organizationId)
+      this._organizationId = removePrefix(
+        assertEx(this.params.organizationId, () => `${moduleName}: Missing organizationId in params`),
+        'org_',
+      )
+    return this._organizationId
+  }
+
+  /**
+   * The Rebilly Publishable API key
+   */
+  protected get publishableApiKey(): string {
+    if (!this._publishableApiKey)
+      this._publishableApiKey = assertEx(this.params.publishableApiKey, () => `${moduleName}: Missing publishableApiKey in params`)
+    return this._publishableApiKey
+  }
+
+  /**
+   * The Rebilly Organization token creation endpoint
+   */
+  protected get tokenEndpoint() {
+    if (!this._tokenEndpoint) this._tokenEndpoint = `${this.apiRoot}/tokens`
+    return this._tokenEndpoint
+  }
+
+  override async reportHandler(payloads?: Payload[]): Promise<Payload[]> {
+    await this.started('throw')
+    const results: WithSources<IdPayload>[] = []
+    // Verify necessary inputs and if nothing meets our criteria, bail early
+    if (!payloads || payloads.length === 0) return results
+    const paymentCard = payloads?.find(isPaymentCard)
+    if (!paymentCard) return results
+    const billingAddress = payloads?.find(isBillingAddress)
+    if (!billingAddress) return results
+    const axios = new AxiosJson({ headers: this.headers })
+    try {
+      const data = toTokenRequest(paymentCard, billingAddress)
+      const response = await axios.post<CreateTokenResponse>(this.tokenEndpoint, data)
+      assertEx(response.status === HttpStatusCode.Created, () => `Failed to tokenize payment card: ${response.status}`)
+      const token = response.data
+      const sources = await PayloadBuilder.dataHashes([paymentCard, billingAddress])
+      results.push({ salt: token.id, schema: IdSchema, sources })
+    } catch (error) {
+      this.logger?.error?.(`${moduleName}: Error creating payment token: ${error}`)
+    }
+    return results
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './Config'
+export * from './Params'
+export * from './Schema'
+export * from './Sentinel'

package/src/util/index.ts

@@ -0,0 +1 @@
+export * from './toTokenRequest'

package/src/util/toTokenRequest.ts

@@ -0,0 +1,24 @@
+import { BillingAddress, PaymentCard } from '@xyo-network/payment-payload-plugins'
+
+import { CreatePaymentTokenRequest } from '../Api'
+
+/**
+ * Converts a payment card and billing address to a token request
+ * @param paymentCard The payment card
+ * @param billingAddress The billing address
+ * @returns The token request
+ */
+export const toTokenRequest = (paymentCard: PaymentCard, billingAddress: BillingAddress): CreatePaymentTokenRequest => {
+  const { cvv, expMonth, expYear, cardNumber } = paymentCard
+  // NOTE: We are destructuring all but the schema and passing it along to the billingAddress. This
+  // is to allow for missing fields to be omitted rather than set to undefined and for any new fields
+  // that might be added later to be automatically picked up on. It is fine to pass this along since
+  // the user is supplying this data about themselves.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { schema: _, ...fields } = billingAddress
+  return {
+    billingAddress: { ...fields },
+    method: 'payment-card',
+    paymentInstrument: { cvv, expMonth, expYear, pan: cardNumber },
+  }
+}

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json"
+}

package/xy.config.ts

@@ -0,0 +1,14 @@
+import { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
+const config: XyTsupConfig = {
+  compile: {
+    browser: {
+      src: true,
+    },
+    node: {
+      src: true,
+    },
+  },
+}
+
+// eslint-disable-next-line import/no-default-export
+export default config