{"_id":"@alsharie/floosak","name":"@alsharie/floosak","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alsharie/floosak","version":"1.0.0","description":"A TypeScript client for the Floosak Online Payment API by QualityConnect.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"echo \"Error: no test specified\" && exit 1","prepublishOnly":"npm run build"},"repository":{"type":"git","url":"git+https://github.com/alsharie/floosak-payment-js.git"},"keywords":["floosak","yemen","payment","sdk","api"],"author":{"name":"abdulrahman alsharie"},"license":"MIT","dependencies":{"axios":"^1.6.0"},"devDependencies":{"@types/node":"^20.9.0","typescript":"^5.2.2"},"_id":"@alsharie/floosak@1.0.0","gitHead":"9d6b1fdd63609d448708ddd837e4bd2ae7aa368c","bugs":{"url":"https://github.com/alsharie/floosak-payment-js/issues"},"homepage":"https://github.com/alsharie/floosak-payment-js#readme","_nodeVersion":"22.11.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-bHHyc6QqIkt4OdooEH6GEuajRzVV6j6n/e7aMY3AdrCjsRzk5jcwR/3VtGFJT0t+MFlTztVOumvhUbRysokWQw==","shasum":"2779588cfbdce7208979cfe1dd510cec0be04f80","tarball":"https://registry.npmjs.org/@alsharie/floosak/-/floosak-1.0.0.tgz","fileCount":8,"unpackedSize":15856,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCYsF/7uGARxWg5G3F54O2MAtOPHjVMfiN3sFBEfrd0mwIhAOtAVLUfbxUB8e8UDthoqnSXDy+dGq7OrFYOMwgOoXhd"}]},"_npmUser":{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com","actor":{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com","type":"user"}},"directories":{},"maintainers":[{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/floosak_1.0.0_1750144606019_0.8387601008758268"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-17T07:16:45.919Z","1.0.0":"2025-06-17T07:16:46.240Z","modified":"2025-06-17T07:16:46.527Z"},"maintainers":[{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"}],"description":"A TypeScript client for the Floosak Online Payment API by QualityConnect.","homepage":"https://github.com/alsharie/floosak-payment-js#readme","keywords":["floosak","yemen","payment","sdk","api"],"repository":{"type":"git","url":"git+https://github.com/alsharie/floosak-payment-js.git"},"author":{"name":"abdulrahman alsharie"},"bugs":{"url":"https://github.com/alsharie/floosak-payment-js/issues"},"license":"MIT","readme":"# Floosak Payment API Client - @alsharie/floosak\r\n\r\nA modern, fully-typed TypeScript client for the [Floosak Online Payment API]. This package simplifies the integration process by providing a clean, promise-based interface for all API endpoints described in the official documentation.\r\n\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @alsharie/floosak\r\n```\r\n\r\n## Usage\r\n\r\n### 1. Initialization\r\n\r\nFirst, import and initialize the `FloosakClient`. You will need your credentials from QualityConnect.\r\n\r\n```typescript\r\nimport { FloosakClient } from '@alsharie/floosak';\r\n\r\nconst client = new FloosakClient({\r\n  baseUrl: 'https://api.your-floosak-provider.com', // Replace with the actual API base URL\r\n  phone: '967705111013',      // Your merchant phone number\r\n  shortCode: '777715',        // Your merchant short code\r\n});\r\n```\r\n\r\n### 2. Authentication\r\n\r\nAuthentication is a two-step process. The token is valid for one year, so you should **store it securely** and reuse it.\r\n\r\n```typescript\r\nimport { FloosakClient } from '@alsharie/floosak';\r\n\r\n// The OTP will be sent to your merchant phone via SMS\r\nconst getOtpFromUser = async (): Promise<string> => {\r\n  // In a real app, you would prompt the user to enter the OTP\r\n  // For this example, we'll hardcode it.\r\n  return '123456';\r\n};\r\n\r\nconst authenticate = async (client: FloosakClient) => {\r\n  try {\r\n    // Step 1: Request an authentication key\r\n    const { request_id } = await client.requestAuthKey();\r\n    console.log(`Authentication requested. Request ID: ${request_id}`);\r\n\r\n    // Step 2: Get the OTP from the user and verify\r\n    const otp = await getOtpFromUser();\r\n    const authResponse = await client.verifyAuthKey({ request_id, otp });\r\n    \r\n    console.log('Authentication successful!');\r\n    \r\n    // --> IMPORTANT: Securely store this token! <--\r\n    const token = authResponse.key; \r\n    console.log('Your new token is:', token);\r\n    \r\n    // You can also get it directly from the client instance\r\n    // const token = client.getToken();\r\n    \r\n    return token;\r\n  } catch (error) {\r\n    console.error('Authentication failed:', error.response?.data || error.message);\r\n  }\r\n};\r\n\r\n// Run the authentication\r\n// authenticate(client);\r\n```\r\n\r\n#### Reusing a Token\r\n\r\nTo avoid authenticating every time, initialize the client with your stored token.\r\n\r\n```typescript\r\nconst storedToken = 'eyJ0eX...'; // Load your saved token\r\n\r\nconst client = new FloosakClient({\r\n  baseUrl: 'https://api.your-floosak-provider.com',\r\n  phone: '967705111013',\r\n  shortCode: '777715',\r\n  token: storedToken, // Provide the existing token\r\n});\r\n\r\n// Now you can directly make payment requests without re-authenticating.\r\n```\r\n\r\n### 3. Making a Payment (P2MCL)\r\n\r\nMaking a payment is also a two-step process involving the merchant and the customer.\r\n\r\n1.  **Purchase Request**: The merchant initiates the transaction. This sends an OTP to the **customer's phone**.\r\n2.  **Purchase Confirm**: The merchant uses the customer's OTP to confirm and complete the payment.\r\n\r\n```typescript\r\nimport { v4 as uuidv4 } from 'uuid'; // A good way to generate unique request IDs\r\n\r\nconst makePayment = async (client: FloosakClient) => {\r\n  try {\r\n    // You must be authenticated first\r\n    if (!client.getToken()) {\r\n        console.log(\"Please authenticate first.\");\r\n        // await authenticate(client); // Uncomment to run auth\r\n        return;\r\n    }\r\n  \r\n    // Step 1: Initiate the purchase request\r\n    const purchaseDetails = {\r\n      source_wallet_id: 144, // Your wallet ID (from verifyAuthKey response)\r\n      request_id: uuidv4(),  // A unique ID for this specific request\r\n      target_phone: '967777841622', // Customer's phone number\r\n      amount: 100,\r\n      purpose: 'Payment for order #XYZ-123',\r\n    };\r\n    \r\n    const requestResponse = await client.purchaseRequest(purchaseDetails);\r\n    const purchaseId = requestResponse.data.id;\r\n    console.log(`Purchase request sent. Awaiting confirmation for purchase ID: ${purchaseId}`);\r\n\r\n    // Step 2: Get the OTP from the customer and confirm the payment\r\n    const customerOtp = 123456; // In a real app, you would prompt the customer to enter this OTP\r\n    \r\n    const confirmResponse = await client.purchaseConfirm({\r\n      purchase_id: purchaseId,\r\n      otp: customerOtp,\r\n    });\r\n    \r\n    console.log('Payment successful!');\r\n    console.log('Transaction Details:', confirmResponse.data);\r\n\r\n  } catch (error) {\r\n    console.error('Payment failed:', error.response?.data || error.message);\r\n  }\r\n};\r\n\r\n// makePayment(client);\r\n```\r\n\r\n### 4. Refunding a Transaction\r\n\r\nYou can refund a completed transaction using its `transaction_id` (which is the `id` from a successful `purchaseConfirm` response).\r\n\r\n```typescript\r\nimport { v4 as uuidv4 } from 'uuid';\r\n\r\nconst refundPayment = async (client: FloosakClient, transactionId: number) => {\r\n    try {\r\n        const refundDetails = {\r\n            transaction_id: transactionId,\r\n            request_id: uuidv4(), // A new unique ID for the refund request\r\n            amount: 100, // Can be a partial or full amount\r\n        };\r\n\r\n        const refundResponse = await client.refund(refundDetails);\r\n        console.log('Refund processed successfully:', refundResponse);\r\n\r\n    } catch (error) {\r\n        console.error('Refund failed:', error.response?.data || error.message);\r\n    }\r\n}\r\n\r\n// Example: refunding transaction with ID 267316\r\n// refundPayment(client, 267316);\r\n```\r\n\r\n## API\r\n\r\nSee `src/types.ts` for a full definition of all request payloads and response objects. The main methods on the `FloosakClient` are:\r\n\r\n-   `requestAuthKey()`\r\n-   `verifyAuthKey(payload)`\r\n-   `purchaseRequest(payload)`\r\n-   `purchaseConfirm(payload)`\r\n-   `refund(payload)`\r\n-   `getToken()`\r\n\r\n","readmeFilename":"README.md","_rev":"1-32b8c542ac0beb346643ac2265a7ab33"}