genuka/GenukaDeveloper.md

Javascript(TS) Package to use Genuka API for a StoreFront website

2. Checklist for App Submissions to Genuka
Below is a non-exhaustive checklist covering best practices and potential compliance or review requirements. You can adapt or expand these based on your platform’s policies.

HMAC Verification

Verify that you are checking the query string parameters (e.g. company_id, code, hmac, timestamp) and comparing them to a hash generated with your clientSecret.
Deny installation or access if the HMAC is invalid.
Secure OAuth Flow

Properly request and exchange the OAuth code with your clientId/clientSecret.
Do not expose clientSecret in client-side code.
Store the access token in a secure server-side store (e.g. database, encrypted config).
No Front-End Exposure of Sensitive Credentials

The developer’s app must not pass the permanent company token to the browser.
All calls to Genuka’s API that require the token must be done server-side.
Any ephemeral tokens (e.g., short-lived JWT or session tokens) used client-side should have limited scope and short expiration.
App Embedding & Frame-Security

If your app is embedded in Genuka’s Admin (via an iframe), ensure you handle the required frame headers (if any) and properly manage session cookies.
Consider implementing CSRF protection if your app does form submissions or other state-changing operations.
Privacy Policy & Data Handling

The developer should supply a Privacy Policy that explains how they handle merchant and customer data.
They must not store or process personal data (like customer details, addresses, order data) in ways that violate laws (GDPR, etc.) or Genuka’s policies.
App Uninstallation Cleanup

On many platforms (like Shopify), an “uninstall” webhook is sent to the app so the developer can do cleanup tasks (like removing database records, revoking tokens, etc.).
If Genuka has a similar mechanism (e.g. a callback on uninstall), the app developer should handle it gracefully.
Error Handling & Logging

The app should properly handle API errors (e.g., expired tokens, 4xx/5xx responses) and respond gracefully in the UI.
The developer should implement a safe logging approach, avoiding logging sensitive tokens in plain text.
Performance & Rate Limits

The app should handle potential rate limits from Genuka’s API.
If the app is heavily used, ensure it’s using caching or batching calls where appropriate.
User Experience

The embedded UI (in the Genuka Admin) should respect the available iframe real estate, not force the user to open it in a separate tab (unless that’s a known or approved pattern).
Provide clear instructions or onboarding within the app so merchants know what to do after installing.
Versioning & Updates

If Genuka’s API versions update periodically, confirm the app is pinned to the correct version (e.g., 2023-11) and includes a plan to upgrade.
Naming & Branding
Follow any naming conventions or branding guidelines (e.g., referencing “Genuka” properly, not using restricted terms, etc.).
Use official Genuka logos, colors, or brand assets only if permitted by your platform’s brand guidelines.
App Review Documentation
Provide a quick guide or “demo” for the reviewer to test your app flow: from installation, to usage, to uninstallation.
If there’s a special test merchant or sandbox environment, document how the review team can log in and see the app in action.
Additional Security Checks (as needed)
If your app interacts with webhooks, ensure you also verify webhook signatures.
If your app stores or processes payment details or other highly sensitive data, you may need PCI or other compliance.
Ensure your site uses HTTPS.
Terms of Service
Provide a Terms of Service so the merchant knows their rights and limitations regarding using the app.