Lnkflow conversions

LnkFlow Conversions

Build or evaluate a conversion integration without guessing about repository evidence, external dashboard state, or legal conclusions. Support any language, framework, checkout provider, consent manager, and deployment model.

Choose the mode

Infer one primary mode from the request:

1. Plan — discover the stack and requirements, then return a decision-ready plan.
2. Implement — inspect the repository, confirm material unknowns, change code, and verify it.
3. Audit — inspect only; report repository evidence, gaps, risks, and external unknowns.
4. Repair — start with an audit, propose the smallest safe repair, then edit only when the user authorized changes.
5. Explain — answer from the product contract and make no changes.

If the request combines modes, perform them in that order. An audit request does not authorize edits. A repository-only audit cannot prove Stripe, LnkFlow dashboard, DNS, CMP dashboard, or production deployment state.

Load only the needed references

• Always read product-contract.md.
• For planning or implementation, read discovery-and-planning.md.
• For browser capture, Stripe, or checkout work, read browser-and-stripe.md.
• For API, backend, or non-Stripe work, read server-api.md.
• For cookies, consent, privacy, or regional questions, read privacy-and-consent.md.
• For audits, repairs, or go-live verification, read audit-and-verification.md.

Treat the bundled contract as the supported LnkFlow behavior. If live LnkFlow documentation is available and conflicts with it, stop and surface the conflict rather than silently choosing one.

Establish evidence first

When a repository is available:

1. Read its agent instructions and preserve unrelated work.

2. Detect languages, frameworks, rendering model, payment SDKs, auth/customer IDs, CMP, deployment layout, and test conventions.

3. Run the read-only scanner:

   python3 <skill-dir>/scripts/audit.py <repo-root> --format markdown
   

4. Inspect every file cited by material scanner findings. Regex evidence is a lead, not proof.

5. Search for generated code, serverless functions, checkout creation, webhooks, environment examples, tests, and privacy/CMP hooks the scanner may not understand.

6. Ask only questions that remain material after inspection. Never ask the user for a secret value.

When no repository is available, use the discovery interview and label the result as a proposed design.

Preserve the attribution chain

Every design must cover the applicable links in this chain:

tracked click
  -> lnk_id / provider-native reference
  -> capture in memory
  -> optional consented persistence
  -> lead/customer binding
  -> sale with stable idempotency key
  -> refund with its own stable id
  -> verification in LnkFlow

Use these invariants:

• Keep browser memory capture, device storage, and outbound URL decoration as separate decisions.
• Use window.lnkflow.getClickId() and getPromoCode(); do not parse LnkFlow cookies directly.
• Use a stable internal customer ID for customer_external_id, never a mutable email when a durable ID exists.
• Send integer minor units, such as cents. Do not send decimal major-unit money.
• Use the payment provider's stable invoice/payment/order ID as invoice_id.
• Give each partial refund a distinct refund_id; never reuse the sale ID as the refund ID.
• Keep conversion bearer tokens server-side. Never embed one in browser or mobile client code.
• Treat test and live Stripe accounts, webhook endpoints, secrets, and LnkFlow integrations as separate namespaces.
• Do not call clicks revenue, conversions, or ROI. Only recorded sale/refund data supports those claims.
• Promo code attribution beats click attribution when the configured code matches; preserve both signals for auditability.
• Commission data is a reporting ledger only. LnkFlow does not move or pay money.

Select the integration path

Choose the smallest path that preserves required attribution:

• Tracked link goes directly to a Stripe Payment Link: enable conversion tracking on the LnkFlow link and configure the website-scoped Stripe webhook. The edge adds client_reference_id; no landing-page SDK is needed for that hop.
• Landing site contains hardcoded Stripe Payment Link buttons: install lnk.js site-wide and opt into Stripe decoration. Decide storage and attribution consent independently.
• Backend creates Stripe Checkout Sessions: capture the click/promo in the browser, deliver allowed values to the backend, and set client_reference_id=lnk_<click-id> when creating the Session. Add metadata.lnkflow_customer_id when a stable signed-in customer ID exists.
• Application reports its own lifecycle: call the server-side lead, sale, and refund APIs. This is the universal path for non-Stripe providers and custom billing.
• Hybrid: bind the durable customer at signup with /track/lead, then let Stripe webhooks report purchases and renewals.

Do not add lnk.js merely because it exists. Direct provider links that are already decorated at the edge do not need browser capture unless the journey first lands on another page.

Plan mode

Use the interview in the planning reference. Prefer facts found in code over questions. Resolve:

• conversion events and business identifiers;
• journey shape, pages, domains, apps, and return visits;
• payment provider and exact checkout creation style;
• anonymous versus authenticated customers and subscriptions;
• promo codes, partial refunds, multiple accounts, currencies, and test mode;
• CMP, jurisdictions, controller/processor roles, retention, and consent withdrawal;
• access to LnkFlow and provider dashboards for external validation.

Return:

1. current state and evidence;
2. chosen path and why;
3. data-flow diagram in text;
4. file-level implementation steps;
5. dashboard/external configuration steps;
6. consent and privacy decisions requiring owner or counsel approval;
7. tests, observability, rollout, and rollback;
8. remaining questions and explicit assumptions.

Implement or repair mode

1. Produce a short evidence-backed plan before editing.
2. Reuse the repository's configuration, HTTP, money, logging, error, and test patterns.
3. Implement capture and server reporting as distinct layers.
4. Fail safely: a tracking failure must not create duplicate orders, block payment, or expose credentials.
5. Log status and non-sensitive identifiers only. Never log tokens, signing secrets, full webhook bodies, or unnecessary personal data.
6. Add tests for idempotency, consent transitions, lost cookies, delayed payment, refunds, and dynamic/SPAs when applicable.
7. Run focused tests, formatter/static analysis, then the scanner again.
8. Report local changes separately from external dashboard actions the user must complete.

External writes to Stripe, LnkFlow, a CMP, or production require the user's explicit intent and an exact target. Never create live conversions or refunds as a verification shortcut.

Audit mode

Use the rubric in the audit reference. Report each dimension as one of:

• pass
• partial
• fail
• needs_review
• unknown_external
• not_applicable

Never convert unknown_external into pass. Give each finding:

• severity and confidence;
• file and line evidence where available;
• impact on attribution, money correctness, security, or privacy;
• the smallest recommended action;
• a validation step that would close it.

Use overall repository states:

• not_detected
• incomplete
• review_required
• repository_ready

repository_ready means the checked-in implementation is ready for end-to-end verification. It does not mean production is integrated.

Privacy boundary

This skill provides technical compliance support, not legal advice. Do not claim that:

• first-party means consent-free;
• cookie-free URL decoration is automatically exempt;
• legitimate interest overrides device-storage consent rules;
• one CMP category mapping fits every site;
• a fixed 90-day lifetime is lawful everywhere;
• anonymization follows merely from omitting email.

Map purposes and mechanisms, minimize data, honor withdrawal, and identify questions for the user's privacy owner or counsel. For EU/EEA and UK traffic, default non-essential storage and attribution forwarding to disabled until the site's approved consent signal enables them unless documented counsel-approved reasoning says otherwise.

Completion gate

Before declaring work complete, confirm:

• a fresh tracked visit produces the expected click reference;
• the reference survives exactly as long and as broadly as intended;
• the checkout or API receives it without exposing secrets;
• retries do not duplicate sales or refunds;
• delayed Stripe payments and renewals use the required webhook events;
• consent grant, denial, change, and withdrawal work;
• test events are excluded from real reporting;
• an attributed sale and its refund reconcile in LnkFlow;
• every external-only check remains clearly assigned.