docs: add end-to-end SDK app integration blueprint

[Hakimziyech18]

Summary

Closes #283.

This PR adds an end-to-end application integration blueprint showing how mobile and third-party application developers can safely combine the PocketPay SDK’s configuration, diagnostics, wallet, account, payment, transaction, Soroban, vault and error-handling modules.

The existing docs/app_integration_blueprint.md placeholder has been expanded into a complete application-level guide, supported by a typed runnable example and links from the root and examples READMEs.

Changes

• Expanded docs/app_integration_blueprint.md into a full integration guide.
• Added examples/app-integration-blueprint.ts as a typed end-to-end Testnet example.
• Added the blueprint to the root README.md documentation index.
• Added the runnable example to examples/README.md.
• Used SDK functions and types exported through the public package root.
• Made no changes to SDK implementation files or public API behaviour.

Blueprint coverage

The guide now covers:

• Early SDK configuration validation
• Opt-in diagnostics and support-safe reporting
• Wallet creation and restoration
• Secure secret-key storage responsibilities
• Read-only and signing-capable account abstractions
• Balance and transaction-history loading
• Payment preview, confirmation and submission
• Issued-asset and trustline considerations
• Transaction uncertainty and duplicate-payment prevention
• Generic Soroban contract-client integration
• Vault readiness, deposits, withdrawals and balance queries
• Returned vault failures and thrown SDK errors
• Safe error classification and recovery behaviour
• Mobile, browser and backend security considerations
• Production-readiness and integration checklists

The document also includes structured lifecycle and sequence diagrams to show how the SDK modules fit together in a complete application flow.

Security considerations

The blueprint clearly warns consumers not to:

• Log or persist unencrypted Stellar secret keys
• Store secret keys in ordinary application state or browser storage
• Log signed XDR, raw signing material, seed phrases or full network payloads
• Blindly retry transactions with an unknown submission status
• Trust an unverified or user-controlled vault contract ID
• Treat the current vault bookkeeping implementation as real token custody

It recommends encrypted device storage, OS keychains, external signers or reviewed backend/HSM boundaries depending on the application architecture.

Testing and verification

Passed

• New integration example TypeScript check:

npx tsc \
  --noEmit \
  --target ES2020 \
  --module commonjs \
  --moduleResolution node \
  --esModuleInterop \
  --skipLibCheck \
  --strict \
  --types node \
  examples/app-integration-blueprint.ts

Result: passed.

• Repository lint completed successfully after temporarily working around an existing upstream StellarSDK.BASE_FEE typing issue in src/network/fee.ts.
• Repository build completed successfully with the same temporary verification-only workaround.
• The temporary source-file change was restored and is not included in this PR.
• git diff --check passed.
• Documentation and example links were verified.
• The final diff contains only the four files related to issue Add SDK end-to-end app integration blueprint #283.

Existing upstream verification failures

The full npm run verify command does not currently pass on upstream/main because of unrelated existing repository issues, including:

• Circular dependency:

network/index.ts -> network/fee.ts -> network/index.ts

• Existing TypeScript arithmetic errors involving StellarSDK.BASE_FEE in src/network/fee.ts.
• A broken deep import in tests/external_signer.test.ts.
• Existing destination-validation tests using invalid Stellar public-key fixtures.
• Existing retry-policy and idempotency tests expecting older error codes such as PAYMENT_FAILED and SEND_ERROR instead of the current TX_BAD_SEQUENCE and NET_RATE_LIMITED classifications.
• An existing typed-asset fixture failure.

Test result during verification:

Test Files: 5 failed, 48 passed, 1 skipped
Tests: 45 failed, 1002 passed, 1 skipped

None of the failing source or test files are modified by this PR.

Acceptance criteria

• Integration blueprint is added.
• Wallet flow is covered.
• Account flow is covered.
• Payment flow is covered.
• Transaction flow is covered.
• Soroban integration is covered.
• Vault flow is covered.
• Error handling is included.
• Diagnostics guidance is included.
• Security cautions are included.
• Typed examples use public SDK exports.
• README links to the guide.
• Examples README links to the runnable example.

Files changed

README.md
docs/app_integration_blueprint.md
examples/README.md
examples/app-integration-blueprint.ts