examples

examples/ — the source of truth for docs code samples

The Wefunder API docs (docs.wefunder.com) show idiomatic SDK code on every operation. Those snippets are not hand-transcribed into the docs site — they're authored here, gated against the real SDK, and published as a verified JSON artifact the docs build consumes. This keeps the examples from rotting: if the SDK surface changes and an example no longer compiles (or no longer runs), CI in this repo goes red.

This file is the cross-language contract. wefunder-python and wefunder-ruby mirror it exactly — same manifest shape, same key scheme, language-appropriate markers — so the docs build treats all three identically.

How it works

Author a real, compilable example here. Each file exports example(wf) (or is a runnable guide script). A // #region <key> … // #endregion block marks the snippet shown in the docs; everything outside it (imports, the example(wf) wrapper, the client bootstrap) is harness and is never shipped.

// examples/listOfferings.ts
import type { Wefunder } from "../src/index.js";   // harness — not shown
export async function example(wf: Wefunder) {
  // #region listOfferings
  const page = await wf.offerings.list({ sort: "most_raised" });
  for (const offering of page.data ?? []) console.log(offering.id);
  // #endregion
  return page;
}

Build the manifest: npm run build:examples → examples_manifest.json.
Gates (CI):
- Compile — npm run typecheck:examples (tsc -p tsconfig.examples.json). A renamed method or changed signature breaks every affected example in this PR's checks.
- Coverage — test/examples.coverage.test.ts: every public operationId in spec/openapi.yaml has an example here OR is listed in coverage-allowlist.json (curl-only). When sync-spec pulls a new API operation, the missing example fails CI — that's how an API change propagates into the SDK as a visible to-do.
- Freshness — same test: the committed examples_manifest.json matches the builder output, so a stale manifest can't be merged.
- Run (where possible) — test/e2e/examples.e2e.test.ts executes the read:public examples against the live sandbox, catching behavioral drift (still compiles, no longer works). Only this repo can do this (it has sandbox creds).
Docs consume the manifest. The docs build fetches examples_manifest.json from each SDK repo by version tag and injects it as OpenAPI x-codeSamples, so the SDK call becomes the default sample on the JavaScript/Python/Ruby tab. cURL stays postman-generated as the universal fallback. The docs site owns all rendering; this repo owns the example content and its verification.

Manifest schema (the contract)

{
  "manifestVersion": 1,
  "lang": "JavaScript",        // MUST equal the docs tab label (JavaScript | Python | Ruby)
  "label": "@wefunder/sdk",    // shown on the tab
  "sdkVersion": "0.1.0-beta.5",
  "apiVersion": "2025-01-15",  // the Wefunder-Version the SDK pins
  "samples": {                 // keyed by operationId — the join key across spec + all langs
    "listOfferings": "const page = await wf.offerings.list(...);\n…"
  }
}

Key scheme

operationId (listOfferings, createWebhookSubscription) — binds to that operation's docs page automatically.
guides/<name> (guides/client-credentials) — an arbitrary snippet for a narrative guide page, referenced explicitly by that page. Same pipeline, same gates; the only difference is the docs page names the key instead of the operation auto-binding to it.

Adding an example

Create examples/<operationId>.ts exporting example(wf), with a #region <operationId>.
npm run build:examples && npm run typecheck:examples && npm test.
Remove the operationId from coverage-allowlist.json (the coverage gate enforces this).
If it's read:public-safe and self-contained, add it to test/e2e/examples.e2e.test.ts.

Mirroring this in another language

Produce an examples_manifest.json with the same shape (lang/label differ; comment markers are language-native — # region/# endregion for Python/Ruby). Wire the same three gates in that repo's native toolchain (pyright+pytest, sorbet/rbs+rspec). Tag the manifest at release. The docs build needs no changes beyond adding the new version to its version map.

Framework-integration examples (not yet gated)

oauth-pkce-server.ts and webhook-receiver.ts are runnable Express illustrations. They pull in express, which we deliberately keep out of the SDK's devDeps, so they're currently excluded from the compile gate (tsconfig.examples.json) and the manifest (no #region). TODO: when wiring the guide pages, either add express/@types/express as devDeps and #region-key these, or relocate them to examples/integrations/ with their own gate.

Name		Name	Last commit message	Last commit date
parent directory ..
README.md		README.md
_boot.ts		_boot.ts
client-credentials.ts		client-credentials.ts
coverage-allowlist.json		coverage-allowlist.json
createInstallation.ts		createInstallation.ts
createInstallationToken.ts		createInstallationToken.ts
createIntent.ts		createIntent.ts
createWebhookEndpoint.ts		createWebhookEndpoint.ts
createWebhookSubscription.ts		createWebhookSubscription.ts
deleteWebhookEndpoint.ts		deleteWebhookEndpoint.ts
deleteWebhookSubscription.ts		deleteWebhookSubscription.ts
followCompany.ts		followCompany.ts
getAttributionMe.ts		getAttributionMe.ts
getAttributionStats.ts		getAttributionStats.ts
getCompany.ts		getCompany.ts
getCompanyDisclosures.ts		getCompanyDisclosures.ts
getCompanyPitch.ts		getCompanyPitch.ts
getCompanyUpdate.ts		getCompanyUpdate.ts
getCurrentUser.ts		getCurrentUser.ts
getInstallation.ts		getInstallation.ts
getIntent.ts		getIntent.ts
getInvestment.ts		getInvestment.ts
getOffering.ts		getOffering.ts
getOfferingStats.ts		getOfferingStats.ts
getPortfolio.ts		getPortfolio.ts
getSyndicate.ts		getSyndicate.ts
getSyndicatePortfolio.ts		getSyndicatePortfolio.ts
getWebhookEndpoint.ts		getWebhookEndpoint.ts
getWebhookSubscription.ts		getWebhookSubscription.ts
install-target.ts		install-target.ts
listActivity.ts		listActivity.ts
listAttributedInvestments.ts		listAttributedInvestments.ts
listAttributionCampaigns.ts		listAttributionCampaigns.ts
listCampaigns.ts		listCampaigns.ts
listCompanyInvestmentChanges.ts		listCompanyInvestmentChanges.ts
listCompanyQuestions.ts		listCompanyQuestions.ts
listCompanyUpdates.ts		listCompanyUpdates.ts
listConnectedApps.ts		listConnectedApps.ts
listEligibleInstallTargets.ts		listEligibleInstallTargets.ts
listFollowedCompanies.ts		listFollowedCompanies.ts
listInstallations.ts		listInstallations.ts
listIntents.ts		listIntents.ts
listInvestments.ts		listInvestments.ts
listMyCompanies.ts		listMyCompanies.ts
listOfferings.ts		listOfferings.ts
listPortfolioPositions.ts		listPortfolioPositions.ts
listSyndicatePortfolioPositions.ts		listSyndicatePortfolioPositions.ts
listSyndicates.ts		listSyndicates.ts
listWebhookEndpoints.ts		listWebhookEndpoints.ts
listWebhookSubscriptions.ts		listWebhookSubscriptions.ts
oauth-pkce-server.ts		oauth-pkce-server.ts
previewIntent.ts		previewIntent.ts
reenableWebhookEndpoint.ts		reenableWebhookEndpoint.ts
revokeInstallation.ts		revokeInstallation.ts
rotateWebhookEndpointSecret.ts		rotateWebhookEndpointSecret.ts
searchCompanies.ts		searchCompanies.ts
testWebhookEndpoint.ts		testWebhookEndpoint.ts
testWebhookSubscription.ts		testWebhookSubscription.ts
unfollowCompany.ts		unfollowCompany.ts
updateWebhookEndpoint.ts		updateWebhookEndpoint.ts
user-token.ts		user-token.ts
webhook-receiver.ts		webhook-receiver.ts

FilesExpand file tree

examples

Directory actions

More options

Directory actions

More options

Latest commit

History

examples

Folders and files

parent directory

README.md

examples/ — the source of truth for docs code samples

How it works

Manifest schema (the contract)

Key scheme

Adding an example

Mirroring this in another language

Framework-integration examples (not yet gated)