pluspay-a2a-react-native 0.1.0

package/src/client.ts

@@ -0,0 +1,137 @@
+import Native from './NativePluspayA2aReactNative';
+import { PPA2AException } from './models/exceptions';
+import type { PPRequest } from './models/requests';
+import type {
+  PPEodResponse,
+  PPMultiPaymentResponse,
+  PPOrderPaymentResponse,
+  PPParametersResponse,
+  PPStartPaymentResponse,
+} from './models/responses';
+
+/**
+ * Main client for PlusPay POS+ App2App (A2A) integration (Android only).
+ *
+ * Usage:
+ * ```ts
+ * const pp = new PPA2AClient();
+ * await pp.initialize();
+ * try {
+ *   const res = await pp.startPayment(
+ *     PPStartPaymentRequestModel.toRequest({
+ *       orderCode: 'ORD001',
+ *       totalAmount: 100,
+ *       paymentType: PPPaymentType.POS,
+ *       paymentMethod: PPPaymentMethod.CC,
+ *     }),
+ *   );
+ * } catch (e) {
+ *   if (e instanceof PPA2AException) console.log(e.errorCode, e.message);
+ * }
+ * ```
+ */
+export class PPA2AClient {
+  private initialized = false;
+  packageName?: string;
+  activityName?: string;
+
+  /** Must be called once before any request. Registers the result receiver. */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+    try {
+      const infoStr = await Native.initialize();
+      const info = infoStr ? JSON.parse(infoStr) : {};
+      this.packageName = info.packageName;
+      this.activityName = info.activityName;
+      this.initialized = true;
+    } catch (e: any) {
+      throw new PPA2AException(
+        e?.code ?? 'INIT_ERROR',
+        e?.message ?? String(e)
+      );
+    }
+  }
+
+  private async send(request: PPRequest): Promise<any> {
+    if (!this.initialized) {
+      throw new PPA2AException(
+        'NOT_INITIALIZED',
+        'PPA2AClient.initialize() must be called first.'
+      );
+    }
+
+    let responseStr: string;
+    try {
+      responseStr = await Native.sendRequest(JSON.stringify(request));
+    } catch (e: any) {
+      throw new PPA2AException(
+        e?.code ?? 'LAUNCH_INTENT_ERROR',
+        e?.message ?? String(e)
+      );
+    }
+
+    let response: any;
+    try {
+      response = responseStr ? JSON.parse(responseStr) : {};
+    } catch (_) {
+      throw new PPA2AException('PP-A2A-PARSE', 'Failed to parse response JSON');
+    }
+
+    if (response?.error_code) {
+      throw new PPA2AException(
+        response.error_code,
+        response.error_message ?? 'Unknown error'
+      );
+    }
+    return response;
+  }
+
+  /** Start a payment on POS+. */
+  startPayment(request: PPRequest): Promise<PPStartPaymentResponse> {
+    return this.send(request);
+  }
+
+  /** Cancel a payment on POS+. */
+  cancelPayment(request: PPRequest): Promise<PPStartPaymentResponse> {
+    return this.send(request);
+  }
+
+  /** Start an EFT POS payment. */
+  startEftPayment(request: PPRequest): Promise<PPStartPaymentResponse> {
+    return this.send(request);
+  }
+
+  /** Cancel an EFT POS payment. */
+  cancelEftPayment(request: PPRequest): Promise<PPStartPaymentResponse> {
+    return this.send(request);
+  }
+
+  /** Start an order payment flow on POS+. */
+  startOrderPayment(request: PPRequest): Promise<PPOrderPaymentResponse> {
+    return this.send(request);
+  }
+
+  /** Start a multi payment flow on POS+. */
+  startMultiPayment(request: PPRequest): Promise<PPMultiPaymentResponse> {
+    return this.send(request);
+  }
+
+  /** Trigger end-of-day (EOD) on POS+. */
+  triggerEod(request: PPRequest): Promise<PPEodResponse> {
+    return this.send(request);
+  }
+
+  /** Trigger parameter update on POS+. */
+  triggerParameters(request: PPRequest): Promise<PPParametersResponse> {
+    return this.send(request);
+  }
+
+  /** Stop listening and clean up native resources. */
+  async dispose(): Promise<void> {
+    try {
+      await Native.dispose();
+    } finally {
+      this.initialized = false;
+    }
+  }
+}

package/src/index.tsx

@@ -0,0 +1,5 @@
+export { PPA2AClient } from './client';
+export { PPA2AException } from './models/exceptions';
+export * from './models/enums';
+export * from './models/requests';
+export * from './models/responses';

package/src/models/enums.ts

@@ -0,0 +1,186 @@
+/**
+ * Enums for the POS+ A2A contract. Values are serialized by their constant
+ * name (e.g. `PPPaymentType.POS` -> `"POS"`); POS+ uses snake_case only for
+ * field names, not for enum values.
+ */
+
+export enum PPTransactionType {
+  POST_PAYMENT_START = 'POST_PAYMENT_START',
+  POST_PAYMENT_CANCEL = 'POST_PAYMENT_CANCEL',
+  POST_EFTPOS = 'POST_EFTPOS',
+  POST_EFTPOS_CANCEL = 'POST_EFTPOS_CANCEL',
+  ORDER_PAYMENT = 'ORDER_PAYMENT',
+  EOD = 'EOD',
+  PARAMETERS = 'PARAMETERS',
+  ORDER_MULTI_PAYMENT = 'ORDER_MULTI_PAYMENT',
+}
+
+export enum PPPaymentType {
+  POS = 'POS',
+  PAYCELL = 'PAYCELL',
+  HEPSIPAY = 'HEPSIPAY',
+  ISTANBULCARD = 'ISTANBULCARD',
+  CASH = 'CASH',
+  ONLINE = 'ONLINE',
+  BANK_TRANSFER = 'BANK_TRANSFER',
+  GASTROPAY = 'GASTROPAY',
+  CIO_CARD = 'CIO_CARD',
+  IWALLET = 'IWALLET',
+  PAYE = 'PAYE',
+  MULTINET = 'MULTINET',
+  METROPOL = 'METROPOL',
+  FASTPAY = 'FASTPAY',
+  TICKET = 'TICKET',
+  EDENRED = 'EDENRED',
+  SETCARD = 'SETCARD',
+  SODEXO = 'SODEXO',
+  GETIRPAY = 'GETIRPAY',
+  TOKENFLEX = 'TOKENFLEX',
+  YEMEKMATIK = 'YEMEKMATIK',
+  ON_CREDIT = 'ON_CREDIT',
+  VIRTUAL_POS = 'VIRTUAL_POS',
+  CUZDANPLUS = 'CUZDANPLUS',
+}
+
+export enum PPPaymentMethod {
+  CC = 'CC',
+  CASH = 'CASH',
+  QR = 'QR',
+  QR_R = 'QR_R',
+  NFC = 'NFC',
+  QUICKCODE = 'QUICKCODE',
+  MOBILE = 'MOBILE',
+  SWIPE = 'SWIPE',
+  NONE = 'NONE',
+  ONLINE = 'ONLINE',
+  TRENDYOL = 'TRENDYOL',
+  GETIR = 'GETIR',
+  YEMEKSEPETI = 'YEMEKSEPETI',
+  MIGROSYEMEK = 'MIGROSYEMEK',
+}
+
+export enum PPPartialPaymentType {
+  AMOUNT = 'AMOUNT',
+  PRODUCT = 'PRODUCT',
+}
+
+export enum PPEodType {
+  POS = 'POS',
+  CASH = 'CASH',
+  BANK_TRANSFER = 'BANK_TRANSFER',
+  ONLINE = 'ONLINE',
+  OTHER = 'OTHER',
+  MULTINET = 'MULTINET',
+  SODEXO = 'SODEXO',
+  SETCARD = 'SETCARD',
+  TICKET = 'TICKET',
+  METROPOL = 'METROPOL',
+  PAYE = 'PAYE',
+  TOKENFLEX = 'TOKENFLEX',
+  EDENRED = 'EDENRED',
+  CUZDANPLUS = 'CUZDANPLUS',
+  IWALLET = 'IWALLET',
+}
+
+export enum PPParameterTypes {
+  bank = 'bank',
+  multinet = 'multinet',
+  metropol = 'metropol',
+  paye = 'paye',
+  iwallet = 'iwallet',
+}
+
+export enum PPCurrencyType {
+  TRY = 'TRY',
+  USD = 'USD',
+  EUR = 'EUR',
+  GBP = 'GBP',
+}
+
+export enum PPProductTypeEnum {
+  PHYSICALLY = 'PHYSICALLY',
+  VIRTUAL = 'VIRTUAL',
+  INFO = 'INFO',
+  MD = 'MD',
+  DSN = 'DSN',
+  QP = 'QP',
+  KFO = 'KFO',
+  COMMISSION = 'COMMISSION',
+  HGS = 'HGS',
+}
+
+export enum PPQtyEnums {
+  ADET = 'ADET',
+  KG = 'KG',
+  GR = 'GR',
+  LT = 'LT',
+  MT = 'MT',
+  KOLI = 'KOLI',
+  PAKET = 'PAKET',
+  PORSIYON = 'PORSIYON',
+}
+
+export enum PPDiscountTypeEnum {
+  PERCENTAGE = 'PERCENTAGE',
+  FIXED_AMOUNT = 'FIXED_AMOUNT',
+}
+
+export enum PPDeliveryTypeEnum {
+  CASH_ORDER = 'CASH_ORDER',
+  PACKAGE_ORDER = 'PACKAGE_ORDER',
+  TABLE_ORDER = 'TABLE_ORDER',
+  TAKE_AWAY = 'TAKE_AWAY',
+  TAKE_CLOSE = 'TAKE_CLOSE',
+}
+
+export enum PPDeliveryStatusEnum {
+  WAITING = 'WAITING',
+  PREPREING = 'PREPREING',
+  READY = 'READY',
+  ONWAY = 'ONWAY',
+  COMPLETE = 'COMPLETE',
+  CANCEL = 'CANCEL',
+}
+
+export enum PPOrderStatusEnum {
+  CANCEL = 'CANCEL',
+  NOT_RESPONSE = 'NOT_RESPONSE',
+  WAITING = 'WAITING',
+  SUCCESS = 'SUCCESS',
+}
+
+export enum PPTransactionStatusEnum {
+  SUCCESS = 'SUCCESS',
+  CANCEL = 'CANCEL',
+  FAIL = 'FAIL',
+  NONE = 'NONE',
+  WAITING = 'WAITING',
+  NOT_RESPONSE = 'NOT_RESPONSE',
+}
+
+export enum PPDocumentTypeEnum {
+  EFATURA = 'EFATURA',
+  EARSIV = 'EARSIV',
+  BILGIFISI = 'BILGIFISI',
+}
+
+export enum PPDocumentStatusEnum {
+  SUCCESS = 'SUCCESS',
+  CANCEL = 'CANCEL',
+  FAIL = 'FAIL',
+  WAITING = 'WAITING',
+  NONE = 'NONE',
+}
+
+export enum PPOrderSourceEnum {
+  POS = 'POS',
+  WEB = 'WEB',
+  KIOSK = 'KIOSK',
+}
+
+export enum PPTransactionTypeEnum {
+  START = 'START',
+  SATIS = 'SATIS',
+  CANCEL = 'CANCEL',
+  REFUND = 'REFUND',
+}

package/src/models/exceptions.ts

@@ -0,0 +1,19 @@
+/**
+ * Thrown when POS+ returns an error (`error_code` / `error_message`) or when
+ * the A2A intent cannot be launched.
+ */
+export class PPA2AException extends Error {
+  readonly errorCode: string;
+
+  constructor(errorCode: string, message: string) {
+    super(message);
+    this.name = 'PPA2AException';
+    this.errorCode = errorCode;
+    // Restore prototype chain (TS target < ES2015 safety).
+    Object.setPrototypeOf(this, PPA2AException.prototype);
+  }
+
+  override toString(): string {
+    return `PPA2AException(${this.errorCode}): ${this.message}`;
+  }
+}

package/src/models/requests.ts

@@ -0,0 +1,302 @@
+import {
+  PPCurrencyType,
+  PPDeliveryStatusEnum,
+  PPDeliveryTypeEnum,
+  PPDiscountTypeEnum,
+  PPEodType,
+  PPParameterTypes,
+  PPPartialPaymentType,
+  PPPaymentMethod,
+  PPPaymentType,
+  PPProductTypeEnum,
+  PPQtyEnums,
+  PPTransactionType,
+} from './enums';
+
+/** Raw A2A request envelope sent to POS+ (`{ data?, header }`). */
+export interface PPRequest {
+  data?: Record<string, any>;
+  header: Record<string, any>;
+}
+
+/** Formats a Date as `yyyy-MM-dd HH:mm` (the format POS+ expects). */
+export function formatOrderDate(date: Date): string {
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}`
+  );
+}
+
+function header(
+  transactionType: PPTransactionType,
+  extra?: { orderCode?: string; transactionId?: string }
+): Record<string, any> {
+  return {
+    transaction_type: transactionType,
+    order_code: extra?.orderCode,
+    transaction_id: extra?.transactionId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Billing & product sub-models
+// ---------------------------------------------------------------------------
+
+export interface PPBillingInfo {
+  name: string;
+  identity: string;
+  phone?: string;
+  email?: string;
+  address?: string;
+  city?: string;
+  district?: string;
+  taxOffice?: string;
+  code?: string;
+}
+
+function billingToJson(b?: PPBillingInfo): Record<string, any> | undefined {
+  if (!b) return undefined;
+  return {
+    name: b.name,
+    identity: b.identity,
+    phone: b.phone,
+    email: b.email,
+    address: b.address,
+    city: b.city,
+    district: b.district,
+    tax_office: b.taxOffice,
+    code: b.code,
+  };
+}
+
+/** Simple product reference used by `startPayment`. */
+export interface PPProduct {
+  id: string;
+  qty?: number;
+}
+
+/** Full product line used by `startMultiPayment`. */
+export interface ProductModel {
+  id: number;
+  sku: string;
+  unit: PPQtyEnums;
+  price: number;
+  title: string;
+  quantity: number;
+  taxRate: number;
+  vatInclude: boolean;
+  productType: PPProductTypeEnum;
+  discountValue: number;
+  description?: string;
+  categoryCode?: string;
+  categoryName?: string;
+  discountType?: PPDiscountTypeEnum;
+  exemptionCode?: string;
+  /** ÖTV oranı. Default 0. */
+  otvOrani?: number;
+  /** Konaklama oranı. Default 0. */
+  konaklamaOrani?: number;
+}
+
+function productToJson(p: ProductModel): Record<string, any> {
+  return {
+    id: p.id,
+    sku: p.sku,
+    unit: p.unit,
+    price: p.price,
+    title: p.title,
+    quantity: p.quantity,
+    tax_rate: p.taxRate,
+    description: p.description,
+    vat_include: p.vatInclude,
+    product_type: p.productType,
+    discount_value: p.discountValue,
+    category_code: p.categoryCode,
+    category_name: p.categoryName,
+    discount_type: p.discountType,
+    exemption_code: p.exemptionCode,
+    otv_orani: p.otvOrani ?? 0,
+    konaklama_orani: p.konaklamaOrani ?? 0,
+  };
+}
+
+export interface TransactionModel {
+  paymentType: PPPaymentType;
+  totalAmount: number;
+  paymentMethod?: PPPaymentMethod;
+}
+
+function transactionToJson(t: TransactionModel): Record<string, any> {
+  return {
+    payment_type: t.paymentType,
+    total_amount: t.totalAmount,
+    payment_method: t.paymentMethod,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Request builders (`*.toRequest`)
+// ---------------------------------------------------------------------------
+
+export const PPStartPaymentRequestModel = {
+  toRequest(params: {
+    orderCode: string;
+    paymentType: PPPaymentType;
+    paymentMethod: PPPaymentMethod;
+    totalAmount: number;
+    installment?: number;
+    isPartial?: boolean;
+    partialType?: PPPartialPaymentType;
+    products?: PPProduct[];
+    billingInformation?: PPBillingInfo;
+  }): PPRequest {
+    return {
+      data: {
+        payment_type: params.paymentType,
+        payment_method: params.paymentMethod,
+        total_amount: params.totalAmount,
+        installment: params.installment,
+        is_partial: params.isPartial ?? false,
+        partial_type: params.partialType,
+        products: (params.products ?? []).map((p) => ({
+          id: p.id,
+          qty: p.qty ?? 1,
+        })),
+        billing_information: billingToJson(params.billingInformation),
+      },
+      header: header(PPTransactionType.POST_PAYMENT_START, {
+        orderCode: params.orderCode,
+      }),
+    };
+  },
+};
+
+export const PPCancelPaymentRequestModel = {
+  toRequest(params: {
+    orderCode: string;
+    transactionId: string;
+    note?: string;
+  }): PPRequest {
+    return {
+      data: { transaction_id: params.transactionId, note: params.note },
+      header: header(PPTransactionType.POST_PAYMENT_CANCEL, {
+        orderCode: params.orderCode,
+      }),
+    };
+  },
+};
+
+export const PPEftPaymentRequestModel = {
+  toRequest(params: {
+    totalAmount: number;
+    paymentType: PPPaymentType;
+    paymentMethod: PPPaymentMethod;
+    transactionId: string;
+    taxRate: number;
+    installment?: number;
+  }): PPRequest {
+    return {
+      data: {
+        total_amount: params.totalAmount,
+        payment_type: params.paymentType,
+        payment_method: params.paymentMethod,
+        transaction_id: params.transactionId,
+        tax_rate: params.taxRate,
+        installment: params.installment,
+      },
+      header: header(PPTransactionType.POST_EFTPOS),
+    };
+  },
+};
+
+export const PPEftCancelRequestModel = {
+  toRequest(params: { transactionId: string; totalAmount: number }): PPRequest {
+    return {
+      data: { total_amount: params.totalAmount },
+      header: header(PPTransactionType.POST_EFTPOS_CANCEL, {
+        transactionId: params.transactionId,
+      }),
+    };
+  },
+};
+
+export const PPOrderPaymentRequestModel = {
+  toRequest(params: { orderCode: string }): PPRequest {
+    return {
+      header: header(PPTransactionType.ORDER_PAYMENT, {
+        orderCode: params.orderCode,
+      }),
+    };
+  },
+};
+
+export const PPEodRequestModel = {
+  toRequest(params?: { types?: PPEodType[]; isAll?: boolean }): PPRequest {
+    return {
+      data: { types: params?.types ?? [], is_all: params?.isAll ?? false },
+      header: header(PPTransactionType.EOD),
+    };
+  },
+};
+
+export const PPParameterRequestModel = {
+  toRequest(params?: {
+    types?: PPParameterTypes[];
+    isAll?: boolean;
+  }): PPRequest {
+    return {
+      data: { types: params?.types ?? [], is_all: params?.isAll ?? false },
+      header: header(PPTransactionType.PARAMETERS),
+    };
+  },
+};
+
+export const PPMultiPaymentRequest = {
+  toRequest(params: {
+    changePaymentStatus: boolean;
+    orderCode: string;
+    orderDate: Date;
+    products: ProductModel[];
+    transactions: TransactionModel[];
+    billingInformation?: PPBillingInfo;
+    groupCode?: string;
+    note?: string;
+    hash?: string;
+    orderNumber?: string;
+    userId?: string;
+    specialCode?: string;
+    startTime?: number;
+    discountAmount?: number;
+    currency?: PPCurrencyType;
+    deliveryStatus?: PPDeliveryStatusEnum;
+    deliveryType?: PPDeliveryTypeEnum;
+    installment?: number;
+    canTryAgain?: boolean;
+  }): PPRequest {
+    return {
+      data: {
+        note: params.note,
+        user_id: params.userId,
+        currency: params.currency ?? PPCurrencyType.TRY,
+        customer: billingToJson(params.billingInformation),
+        hash: params.hash,
+        products: params.products.map(productToJson),
+        group_code: params.groupCode,
+        order_code: params.orderCode,
+        order_date: formatOrderDate(params.orderDate),
+        start_time: params.startTime,
+        installment: params.installment,
+        order_number: params.orderNumber,
+        special_code: params.specialCode,
+        transactions: params.transactions.map(transactionToJson),
+        delivery_type: params.deliveryType ?? PPDeliveryTypeEnum.CASH_ORDER,
+        delivery_status: params.deliveryStatus,
+        discount_amount: params.discountAmount ?? 0,
+        change_payment_status: params.changePaymentStatus,
+        can_try_again: params.canTryAgain ?? true,
+      },
+      header: header(PPTransactionType.ORDER_MULTI_PAYMENT),
+    };
+  },
+};

package/src/models/responses.ts

@@ -0,0 +1,56 @@
+/**
+ * Response models. POS+ returns snake_case JSON; these interfaces describe the
+ * fields as received (no key remapping) plus an index signature so any extra
+ * field POS+ adds stays accessible. Error responses are surfaced as
+ * `PPA2AException` by the client before these are returned.
+ */
+
+export interface PPA2AResponse {
+  [key: string]: any;
+}
+
+export interface PPStartPaymentResponse extends PPA2AResponse {
+  status?: string;
+  order_code?: string;
+  total_amount?: number;
+  total_paid?: number;
+  amount_due?: number;
+  is_partial?: boolean;
+  partial_type?: string;
+  card_number_masked?: string;
+  rrn?: string;
+  payment_type?: string;
+  payment_method?: string;
+}
+
+export interface PPOrderPaymentResponse extends PPA2AResponse {
+  status?: string;
+  completed?: boolean;
+  order_code?: string;
+  total_amount?: number;
+  total_paid?: number;
+  amount_due?: number;
+  grand_total?: number;
+  results?: any[];
+}
+
+export interface PPEodResponse extends PPA2AResponse {
+  success?: boolean;
+  error_message?: string;
+  results?: any[];
+}
+
+export interface PPParametersResponse extends PPA2AResponse {
+  completed?: boolean;
+  error_message?: string;
+  results?: any[];
+}
+
+export interface PPMultiPaymentResponse extends PPA2AResponse {
+  order_code?: string;
+  status?: string;
+  grand_total?: number;
+  total_paid?: number;
+  products?: any[];
+  transactions?: any[];
+}