persian-bank-react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahdi Tasha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,528 @@
+# Persian Bank React
+
+[![npm version](https://img.shields.io/npm/v/persian-bank-react)](https://www.npmjs.com/package/persian-bank-react)
+[![npm downloads](https://img.shields.io/npm/dm/persian-bank-react)](https://www.npmjs.com/package/persian-bank-react)
+[![TypeScript](https://img.shields.io/badge/TypeScript-first-3178C6)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/persian-bank-react)](LICENSE)
+
+A lightweight, TypeScript-first React library for **Iranian bank icons and bank identification utilities**.
+
+Identify Iranian banks from card numbers or SHEBA/IBAN values, and render their bank icons with a simple, type-safe API.
+
+```bash
+npm install persian-bank-react
+```
+
+---
+
+## Why Persian Bank React?
+
+Building Iranian financial interfaces often means maintaining the same bank mappings and icons across multiple projects.
+
+This package brings those pieces into one small, reusable API:
+
+- 🎨 **Bank icons** as scalable inline SVGs
+- 💳 **Card → bank identification** using card BINs
+- 🏦 **SHEBA → bank identification**
+- 🧩 **TypeScript-first** API with autocomplete
+- ⚡ **Zero runtime dependencies** beyond React
+- 🪶 **Lightweight and tree-shakable**
+- 🔒 **No network requests** for bank identification
+- 🌐 Designed for financial products, SaaS applications, dashboards, checkout flows, and internal tools
+
+Instead of maintaining your own bank database and SVG collection:
+
+```tsx
+<BankIcon name="mellat" />
+```
+
+or:
+
+```ts
+const bank = getBankFromCard("6104 3300 0000 0000");
+
+console.log(bank);
+// {
+//   type: "mellat",
+//   name: "بانک ملت"
+// }
+```
+
+---
+
+## Installation
+
+```bash
+npm install persian-bank-react
+```
+
+---
+
+## Quick Start
+
+### Render a bank icon
+
+```tsx
+import { BankIcon } from "persian-bank-react";
+
+export function PaymentMethod() {
+  return (
+    <BankIcon name="mellat" width={48} height={48} aria-label="Bank Mellat" />
+  );
+}
+```
+
+Because the icon component accepts standard SVG props, you can style it with your existing UI system:
+
+```tsx
+<BankIcon name="mellat" className="h-10 w-10" />
+```
+
+---
+
+## Identify a Bank from a Card Number
+
+Use `getBankFromCard()` to identify the issuing bank from an Iranian card number.
+
+```ts
+import { getBankFromCard } from "persian-bank-react";
+
+const bank = getBankFromCard("6037-9900-1234-5678");
+
+if (bank) {
+  console.log(bank.type);
+  console.log(bank.name);
+}
+```
+
+Result:
+
+```ts
+{
+  type: "melli",
+  name: "بانک ملی ایران"
+}
+```
+
+Formatted card numbers are supported:
+
+```ts
+getBankFromCard("6037 9900 1234 5678");
+getBankFromCard("6037-9900-1234-5678");
+getBankFromCard(6037990012345678);
+```
+
+If the bank cannot be identified:
+
+```ts
+const bank = getBankFromCard("123456");
+
+console.log(bank);
+// null
+```
+
+---
+
+## Identify a Bank from SHEBA
+
+Use `getBankFromSheba()` to identify the bank from an Iranian SHEBA/IBAN.
+
+```ts
+import { getBankFromSheba } from "persian-bank-react";
+
+const bank = getBankFromSheba("IR123456789012345678901234");
+
+if (bank) {
+  console.log(bank.type);
+  console.log(bank.name);
+}
+```
+
+Whitespace is automatically ignored:
+
+```ts
+getBankFromSheba("IR12 3456 7890 1234 5678 9012 34");
+```
+
+### SHEBA without `IR`
+
+If your data source provides the 24-digit numeric portion without the `IR` prefix:
+
+```ts
+const bank = getBankFromSheba("123456789012345678901234", true);
+```
+
+---
+
+## Using Icons with Bank Detection
+
+The utilities and icon component are designed to work together.
+
+For example, a payment card component can identify the bank and render its icon:
+
+```tsx
+import { BankIcon, getBankFromCard } from "persian-bank-react";
+
+const bank = getBankFromCard(cardNumber);
+
+return bank ? (
+  <BankIcon name={bank.type} width={40} height={40} aria-label={bank.name} />
+) : null;
+```
+
+This makes it easy to build:
+
+- Payment forms
+- Wallet interfaces
+- Banking dashboards
+- Transaction lists
+- Card selectors
+- Checkout experiences
+- Account management screens
+- Financial SaaS products
+
+---
+
+## API
+
+### `BankIcon`
+
+```tsx
+<BankIcon name="mellat" width={48} height={48} />
+```
+
+#### Props
+
+| Prop           | Type                      | Required |
+| -------------- | ------------------------- | -------- |
+| `name`         | `BankNameType`            | Yes      |
+| SVG attributes | `SVGProps<SVGSVGElement>` | No       |
+
+All standard React SVG properties are supported.
+
+```tsx
+<BankIcon
+  name="pasargad"
+  className="size-8"
+  aria-label="Bank Pasargad"
+  role="img"
+/>
+```
+
+---
+
+### `getBankFromCard`
+
+```ts
+getBankFromCard(cardNumber: string | number): BankInfo | null
+```
+
+Returns the bank associated with the first six digits of an Iranian payment card.
+
+```ts
+const bank = getBankFromCard("6274121234567890");
+```
+
+Returns:
+
+```ts
+{
+  type: "eghtesaade-novin",
+  name: "بانک اقتصاد نوین"
+}
+```
+
+Returns `null` when the card BIN is not supported.
+
+---
+
+### `getBankFromSheba`
+
+```ts
+getBankFromSheba(
+  sheba: string,
+  useIR?: boolean
+): BankInfo | null
+```
+
+Identifies the bank from the four-digit bank code contained in an Iranian SHEBA/IBAN.
+
+```ts
+const bank = getBankFromSheba("IR...");
+```
+
+Returns `null` when the input format is invalid or the bank code is not supported.
+
+---
+
+## Types
+
+The package exposes its main types for TypeScript applications.
+
+```ts
+import type {
+  BankNameType,
+  BankInfo,
+  BankIconPropsType,
+} from "persian-bank-react";
+```
+
+### `BankInfo`
+
+```ts
+interface BankInfo {
+  type: BankNameType;
+  name: string;
+}
+```
+
+### `BankNameType`
+
+`BankNameType` is a union of supported bank identifiers:
+
+```ts
+type BankNameType =
+  | "ayandeh"
+  | "mellat"
+  | "melli"
+  | "parsian"
+  | "pasargad"
+  | "saman"
+  | "tejarat"
+  // ...
+  | "unknown";
+```
+
+Using a union instead of arbitrary strings provides autocomplete and compile-time validation:
+
+```ts
+<BankIcon name="mellat" />     // ✅
+<BankIcon name="pasargad" />   // ✅
+<BankIcon name="something" />  // ❌ TypeScript error
+```
+
+---
+
+## Supported Banks
+
+The package currently includes icons and/or identification mappings for a broad range of Iranian banks and financial institutions, including:
+
+- بانک آینده
+- بانک مرکزی
+- بانک صنعت و معدن
+- بانک ملت
+- بانک رفاه کارگران
+- بانک مسکن
+- بانک سپه
+- بانک کشاورزی
+- بانک ملی ایران
+- بانک تجارت
+- بانک صادرات ایران
+- بانک توسعه صادرات ایران
+- پست بانک
+- بانک توسعه تعاون
+- مؤسسه اعتباری توسعه
+- بانک کارآفرین
+- بانک پارسیان
+- بانک اقتصاد نوین
+- بانک سامان
+- بانک پاسارگاد
+- بانک سرمایه
+- بانک سینا
+- بانک قرض‌الحسنه مهر ایران
+- بانک شهر
+- بانک انصار
+- بانک گردشگری
+- بانک حکمت ایرانیان
+- بانک دی
+- بانک ایران زمین
+- بانک قرض‌الحسنه رسالت
+- بانک خاورمیانه
+- بانک ایران و ونزوئلا
+- بانک قوامین
+- مؤسسه مالی و اعتباری کوثر
+- مؤسسه مالی و اعتباری نور
+
+> Bank coverage may differ between icon availability, card BIN mappings, and SHEBA mappings.
+
+---
+
+## Design & Technical Decisions
+
+### Inline SVG
+
+Bank logos are rendered as inline SVG rather than external image files.
+
+This means icons:
+
+- Scale without losing quality
+- Work well on high-DPI displays
+- Can receive standard SVG attributes
+- Don't require additional image requests
+- Integrate naturally with React component systems
+
+### Local Bank Resolution
+
+Bank identification is performed using local lookup tables.
+
+There are:
+
+- No API calls
+- No external services
+- No network dependency
+- No user data sent anywhere
+
+This makes the utilities predictable and suitable for client-side applications.
+
+### TypeScript-first
+
+The public API is strongly typed so invalid bank identifiers are caught during development rather than at runtime.
+
+### Small API Surface
+
+The package intentionally exposes a small set of focused primitives:
+
+```ts
+BankIcon;
+getBankFromCard;
+getBankFromSheba;
+```
+
+The goal is to make the library easy to learn and difficult to misuse.
+
+---
+
+## Accessibility
+
+Because `BankIcon` renders a native SVG, standard accessibility attributes can be passed directly:
+
+```tsx
+<BankIcon name="mellat" role="img" aria-label="Bank Mellat" />
+```
+
+For decorative icons, hide them from assistive technologies:
+
+```tsx
+<BankIcon name="mellat" aria-hidden="true" />
+```
+
+---
+
+## Example: Card Input
+
+A practical example using the package with a React card input:
+
+```tsx
+import { useState } from "react";
+import { BankIcon, getBankFromCard } from "persian-bank-react";
+
+export function CardInput() {
+  const [cardNumber, setCardNumber] = useState("");
+
+  const bank = getBankFromCard(cardNumber);
+
+  return (
+    <div>
+      <input
+        value={cardNumber}
+        onChange={(event) => setCardNumber(event.target.value)}
+        placeholder="Card number"
+        inputMode="numeric"
+      />
+
+      {bank && (
+        <div>
+          <BankIcon
+            name={bank.type}
+            width={32}
+            height={32}
+            aria-hidden="true"
+          />
+
+          <span>{bank.name}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Important: Identification ≠ Validation
+
+`getBankFromCard()` identifies a bank from the card's BIN.
+
+It does **not** verify that:
+
+- The card number is currently active
+- The card belongs to the person using it
+- The card is valid according to banking infrastructure
+- The card can perform transactions
+
+Likewise, `getBankFromSheba()` identifies the bank from the SHEBA structure; it is **not a complete SHEBA validation service**.
+
+Use dedicated validation logic when your application requires full financial-data validation.
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+If you find:
+
+- A missing bank
+- An incorrect bank mapping
+- An outdated BIN
+- An incorrect SHEBA code
+- A broken icon
+- A TypeScript/API issue
+
+please open an issue or submit a pull request.
+
+When contributing a new bank icon, please keep the implementation consistent with the existing SVG and component conventions.
+
+---
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone <repository-url>
+
+cd persian-bank-react
+
+npm install
+```
+
+Run the development environment:
+
+```bash
+npm run dev
+```
+
+Build the package:
+
+```bash
+npm run build
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+---
+
+## License
+
+MIT © Mahdi Tasha
+
+---
+
+## Author
+
+Built and maintained by **Mahdi Tasha**.

package/dist/index.d.mts

@@ -0,0 +1,87 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { HTMLAttributes } from 'react';
+
+/**
+ * Identifiers for supported Iranian banks and financial institutions.
+ *
+ * The values are intentionally kept as stable, lowercase identifiers
+ * so they can safely be used as component props, lookup keys, and
+ * serialized values.
+ */
+type BankNameType$1 = "ayandeh" | "markazi" | "blue" | "caspian" | "dey" | "eghtesaade-novin" | "future" | "gardeshgari" | "iran-europe" | "iran-venezuela" | "iran-zamin" | "karafarin" | "keshavarzi" | "khavar-mianeh" | "maskan" | "mehr-iran" | "melall" | "mellat" | "melli" | "noor" | "parsian" | "pasargad" | "post" | "refah" | "resalat" | "saderat" | "saman" | "sanat-madan" | "sarmayeh" | "sepah" | "shahr" | "sina" | "standard-chartered" | "taavon-eslami" | "tejarat" | "tosee" | "tosee-sedarat" | "tossee-taavon" | "kosar" | "mehr-eghtesaad" | "ghavamin" | "hekmat" | "ansar" | "unknown";
+/**
+ * Props shared by the BankIcon component.
+ *
+ * Extending SVG HTML attributes allows consumers to use standard
+ * SVG properties such as className, aria-label, width, height,
+ * and other native React SVG attributes.
+ */
+interface BankIconPropsType extends HTMLAttributes<SVGElement> {
+    /** Identifier of the bank whose icon should be rendered. */
+    name: BankNameType$1;
+}
+/**
+ * Metadata associated with a bank.
+ *
+ * `type` is the stable identifier used internally by the icon system,
+ * while `name` represents the human-readable bank name.
+ */
+interface BankInfo$1 {
+    type: BankNameType$1;
+    name: string;
+}
+
+type bankType_BankIconPropsType = BankIconPropsType;
+declare namespace bankType {
+  export type { bankType_BankIconPropsType as BankIconPropsType, BankInfo$1 as BankInfo, BankNameType$1 as BankNameType };
+}
+
+/**
+ * Renders the icon for a supported Iranian bank.
+ *
+ * Each bank icon is kept as an inline SVG so it:
+ * - Scales cleanly at any size.
+ * - Inherits standard SVG/React props from the caller.
+ * - Doesn't require an additional image request.
+ */
+declare function BankIcon({ name, ...props }: BankIconPropsType): false | react_jsx_runtime.JSX.Element;
+
+type BankNameType = "ayandeh" | "markazi" | "blue" | "caspian" | "dey" | "eghtesaade-novin" | "future" | "gardeshgari" | "iran-europe" | "iran-venezuela" | "iran-zamin" | "karafarin" | "keshavarzi" | "khavar-mianeh" | "maskan" | "mehr-iran" | "melall" | "mellat" | "melli" | "noor" | "parsian" | "pasargad" | "post" | "refah" | "resalat" | "saderat" | "saman" | "sanat-madan" | "sarmayeh" | "sepah" | "shahr" | "sina" | "standard-chartered" | "taavon-eslami" | "tejarat" | "tosee" | "tosee-sedarat" | "tossee-taavon" | "kosar" | "mehr-eghtesaad" | "ghavamin" | "hekmat" | "ansar" | "unknown";
+interface BankInfo {
+    type: BankNameType;
+    name: string;
+}
+
+/**
+ * Resolves the issuing bank from an Iranian card number.
+ *
+ * The function accepts both string and numeric input and normalizes
+ * formatting characters such as spaces or hyphens before performing
+ * the BIN lookup.
+ *
+ * @returns Bank metadata when the BIN is recognized; otherwise `null`.
+ */
+declare function getBankFromCard(cardNumber: string | number): BankInfo | null;
+/**
+ * Resolves the issuing bank from an Iranian SHEBA/IBAN number.
+ *
+ * Both formats are supported:
+ * - `IR` prefixed: `IRxxxxxxxxxxxxxxxxxxxxxxxx`
+ * - 24-digit numeric value when `useIR` is enabled
+ *
+ * Whitespace is ignored, making formatted SHEBA values safe to pass
+ * directly to the function.
+ *
+ * @param sheba - Iranian SHEBA/IBAN value.
+ * @param useIR - Whether the supplied value omits the `IR` prefix.
+ * @returns Bank metadata when the bank code is recognized; otherwise `null`.
+ */
+declare function getBankFromSheba(sheba: string, useIR?: boolean): BankInfo | null;
+
+declare const bankUtil_getBankFromCard: typeof getBankFromCard;
+declare const bankUtil_getBankFromSheba: typeof getBankFromSheba;
+declare namespace bankUtil {
+  export { bankUtil_getBankFromCard as getBankFromCard, bankUtil_getBankFromSheba as getBankFromSheba };
+}
+
+export { BankIcon, bankType as Types, bankUtil as Utils };