@wefunder/sdk 0.1.0-beta.0 → 0.1.0-beta.10

package/examples_manifest.json

@@ -0,0 +1,67 @@
+{
+  "manifestVersion": 1,
+  "lang": "JavaScript",
+  "label": "@wefunder/sdk",
+  "sdkVersion": "0.1.0-beta.10",
+  "apiVersion": "2025-01-15",
+  "generatedBy": "scripts/build-examples-manifest.mjs",
+  "samples": {
+    "createInstallation": "const install = await wf.unwrap(\n  wf.raw.createInstallation({\n    body: { target_type: \"company\", target_id: \"co_abc123Example\", scopes: [\"read:offerings\", \"read:investments\"] },\n  }),\n);\nconsole.log(install.data?.id, install.data?.attributes);",
+    "createInstallationToken": "const token = await wf.unwrap(\n  wf.raw.createInstallationToken({ path: { external_id: \"ins_9t2xExample\" }, body: { scopes: [\"read:investments\"] } }),\n);\nconsole.log(token.data);",
+    "createIntent": "const { data: intent } = await wf.unwrap(\n  wf.raw.createIntent({\n    body: {\n      action_name: \"syndicates.close_deal\",\n      resource_type: \"Club\",\n      resource_id: \"syn_example\",\n      params: { fundraise_id: 99 },\n      // Safe to retry: an existing pending/executed intent with this key is returned instead.\n      idempotency_key: \"close-acme-series-a\",\n      requested_by_agent: \"My Deal Bot\",\n    },\n  }),\n);\n// Hand this URL to a human — the action executes only after they approve.\nconsole.log(intent?.attributes?.review_url);",
+    "createWebhookEndpoint": "const endpoint = await wf.webhookEndpoints.create({\n  url: \"https://yourapp.com/webhooks/wefunder\", // public HTTPS (localhost/private IPs rejected)\n  events: [\"offering.opened\", \"investment.executed\", \"investment.changed\"],\n  mode: \"live\",\n});\n// Store this now — it's needed by constructEvent() and is never shown again.\nconst signingSecret = endpoint.attributes?.secret;\nconsole.log(endpoint.id, signingSecret);",
+    "createWebhookSubscription": "const subscription = await wf.unwrap(\n  wf.raw.createWebhookSubscription({\n    path: { campaign_id: 1234 },\n    body: {\n      target_url: \"https://example.com/wefunder/webhooks\",\n      events: [\"investment.confirmed\", \"investment.canceled\"],\n    },\n  }),\n);\nconsole.log(subscription);",
+    "deleteWebhookEndpoint": "const result = await wf.webhookEndpoints.remove(\"whe_8f3ExampleEndpoint00\");\nconsole.log(result.removed); // true",
+    "deleteWebhookSubscription": "await wf.unwrap(wf.raw.deleteWebhookSubscription({ path: { campaign_id: 1234, webhook_id: 56 } }));",
+    "followCompany": "const result = await wf.unwrap(wf.raw.followCompany({ path: { company_id: \"co_abc123Example\" } }));\nconsole.log(result);",
+    "getAttributionMe": "const me = await wf.attribution.me();\nconsole.log(me);",
+    "getAttributionStats": "const stats = await wf.unwrap(\n  wf.raw.getAttributionStats({\n    path: { campaign_id: 1234 },\n    query: { start_date: \"2026-01-01\", end_date: \"2026-03-31\", utm_source: \"newsletter\" },\n  }),\n);\nconsole.log(stats.data);",
+    "getCompany": "const { data: company } = await wf.unwrap(wf.raw.getCompany({ path: { id: \"co_abc123Example\" } }));\nconsole.log(company?.attributes?.name);",
+    "getCompanyDisclosures": "const { data: disclosures } = await wf.unwrap(\n  wf.raw.getCompanyDisclosures({\n    path: { id: \"co_abc123Example\" },\n    query: { sections: [\"business\", \"risks\", \"use_of_funds\"] },\n  }),\n);\nconsole.log(disclosures?.attributes);",
+    "getCompanyPitch": "const { data: pitch } = await wf.unwrap(\n  wf.raw.getCompanyPitch({ path: { id: \"co_abc123Example\" }, query: { sections: [\"story\", \"perks\"] } }),\n);\nconsole.log(pitch?.attributes);",
+    "getCompanyUpdate": "const { data: update } = await wf.unwrap(\n  wf.raw.getCompanyUpdate({ path: { id: \"co_abc123Example\", update_id: \"upd_9t2xExample\" } }),\n);\nconsole.log(update?.attributes?.title);",
+    "getCurrentUser": "const me = await wf.users.me();\nconsole.log(\"Logged in as\", me.id);",
+    "getInstallation": "const { data: install } = await wf.unwrap(wf.raw.getInstallation({ path: { external_id: \"ins_9t2xExample\" } }));\nconsole.log(install?.attributes);",
+    "getIntent": "const intent = await wf.intents.get(\"intent_abc123\");\nconsole.log(intent.attributes?.status); // pending | approved | executed | expired | rejected | failed",
+    "getInvestment": "const investment = await wf.investments.get(\"inv_8f3kQ2Example\");\nconsole.log(investment.status, investment.amounts?.committed_cents, investment.investor?.id);",
+    "getOffering": "const offering = await wf.offerings.get(\"ofr_QfmTyP8qjfYAvkEgREyL3kLf\");\nconsole.log(offering.attributes?.company_name, offering.attributes?.status);",
+    "getOfferingStats": "const { data: stats } = await wf.unwrap(\n  wf.raw.getOfferingStats({ path: { offering_id: \"ofr_QfmTyP8qjfYAvkEgREyL3kLf\" } }),\n);\nconsole.log(stats);",
+    "getPortfolio": "const summary = await wf.portfolio.get();\nconsole.log(\n  summary.attributes?.total_current_value_cents,\n  summary.attributes?.return_multiple,\n);",
+    "getSyndicate": "const syndicate = await wf.syndicates.get(42);\nconsole.log(syndicate.attributes?.name, syndicate.attributes?.deal_count);",
+    "getSyndicatePortfolio": "const { data: summary } = await wf.unwrap(\n  wf.raw.getSyndicatePortfolio({\n    path: { syndicate_id: \"syn_example\" },\n  }),\n);\nconsole.log(summary?.attributes?.total_current_value_cents);",
+    "getWebhookEndpoint": "const endpoint = await wf.webhookEndpoints.get(\"whe_8f3ExampleEndpoint00\");\nconsole.log(endpoint.attributes?.events, endpoint.attributes?.failing_since);",
+    "getWebhookSubscription": "const subscription = await wf.unwrap(\n  wf.raw.getWebhookSubscription({ path: { campaign_id: 1234, webhook_id: 56 } }),\n);\nconsole.log(subscription.data);",
+    "guides/client-credentials": "const wf = await Wefunder.fromClientCredentials({\n  clientId: process.env.WEFUNDER_CLIENT_ID!,\n  clientSecret: process.env.WEFUNDER_CLIENT_SECRET!,\n  scopes: [\"read:public\"],\n});\n\nconsole.log(\"mode:\", wf.mode); // \"live\" or \"test\", from the token prefix\n\n// client_credentials holds only read:public — browse public offerings.\n// (wf.users.me() would throw 403 insufficient_scope: it needs read:profile.)\nfor await (const offering of wf.offerings.all()) {\n  console.log(offering.id);\n}",
+    "guides/install-target": "// 1. Which companies / syndicates may this user install on? (Only those — an investor's\n//    empty list is not a failure.)\nconst targets = await wf.unwrap(\n  wf.raw.listEligibleInstallTargets({ query: { target_type: \"syndicate\" } }),\n);\nfor (const t of targets.data ?? [])\n  console.log(t.id, t.name, t.installed ? \"(already installed)\" : \"\");\n\n// 2. Install. The response carries the install (`data`) AND its token. If the app is\n//    already installed here the API answers 409 `already_installed` — its `details.installation`\n//    is the existing install's id, so mint a fresh token for that instead. Any other error\n//    (revoked install, missing scope) still throws.\nlet installationToken: string | undefined;\ntry {\n  const installed = await wf.unwrap(\n    wf.raw.createInstallation({\n      body: {\n        target_type: \"syndicate\",\n        target_id: syndicateId,\n        scopes: [\"read:syndicates\"],\n      },\n    }),\n  );\n  installationToken = installed.token?.access_token;\n} catch (err) {\n  if (!(err instanceof WefunderError) || err.type !== \"already_installed\")\n    throw err;\n  const existingId = (err.details as { installation?: string } | undefined)\n    ?.installation;\n  if (!existingId) throw err;\n  const minted = await wf.unwrap(\n    wf.raw.createInstallationToken({ path: { external_id: existingId } }),\n  );\n  installationToken = minted.token?.access_token; // shown once — store it\n}\nif (!installationToken) throw new Error(\"no installation token returned\");\n\n// 3. First request AS the installation.\nconst asSyndicate = new Wefunder({ accessToken: installationToken });\nconst deals = await asSyndicate.unwrap(\n  asSyndicate.raw.listSyndicateDeals({ path: { syndicate_id: syndicateId } }),\n);\nconsole.log(deals.data?.length, \"deals\");",
+    "guides/user-token": "// 1. Send the investor to consent. Keep state + the PKCE verifier in their session.\nconst pkce = generatePkce();\nconst state = crypto.randomUUID();\nawait saveAttempt(state, pkce.codeVerifier);\nconst authorizationUrl = createAuthorizationUrl({\n  clientId: process.env.WEFUNDER_CLIENT_ID!,\n  redirectUri: process.env.WEFUNDER_REDIRECT_URI!,\n  scopes: [\"read:investments\"],\n  state,\n  pkce,\n});\n// redirect(authorizationUrl)\n\n// 2. On the callback, exchange the code (after checking `state` matches the session).\nconst tokens = await exchangeCode({\n  clientId: process.env.WEFUNDER_CLIENT_ID!,\n  clientSecret: process.env.WEFUNDER_CLIENT_SECRET, // omit for public clients\n  code: \"AUTHORIZATION_CODE\",\n  redirectUri: process.env.WEFUNDER_REDIRECT_URI!,\n  codeVerifier: pkce.codeVerifier,\n});\n\n// 3. Read their holdings. The access token lasts two hours; the SDK rotates the refresh\n//    token for you and hands every new set to `store.save` — persist the whole thing.\nconst wf = new Wefunder({\n  tokens,\n  clientId: process.env.WEFUNDER_CLIENT_ID!,\n  clientSecret: process.env.WEFUNDER_CLIENT_SECRET,\n  store: { save: (next: TokenSet) => persistTokens(next) },\n});\nconst portfolio = await wf.portfolio.get();\nconsole.log(portfolio.attributes?.total_current_value_cents);",
+    "listActivity": "// Everything my connected apps did to syndicate members, most recent first.\nconst activity = await wf.unwrap(\n  wf.raw.listActivity({\n    query: { action_pattern: \"syndicates.member.*\", status: \"success\" },\n  }),\n);\nfor (const event of activity.data ?? []) {\n  console.log(event.attributes?.action, event.attributes?.created_at);\n}",
+    "listAttributedInvestments": "const investments = await wf.unwrap(\n  wf.raw.listAttributedInvestments({\n    path: { campaign_id: 1234 },\n    query: { start_date: \"2026-01-01\", detail_level: \"anonymized\" },\n  }),\n);\nfor (const investment of investments.data ?? []) {\n  if (\"amount_tier\" in investment) {\n    // Anonymized row: opaque tokens + an amount tier, never exact values or PII.\n    console.log(investment.investor_token, investment.amount_tier, investment.attribution?.utm_source);\n  }\n}",
+    "listAttributionCampaigns": "const campaigns = await wf.unwrap(wf.raw.listAttributionCampaigns());\nconsole.log(campaigns.data);",
+    "listCampaigns": "// Campaigns for companies where the authenticated user is a founder.\nconst page = await wf.campaigns.list();\nfor (const campaign of page.data ?? []) {\n  console.log(campaign.id, campaign.attributes?.company_name, campaign.attributes?.amount_raised);\n}\n\n// Or stream every campaign lazily, one page fetched at a time:\nfor await (const campaign of wf.campaigns.all()) {\n  console.log(campaign.attributes?.state);\n}",
+    "listCompanyInvestmentChanges": "// Walk every change for one company. Persist meta.next_cursor after each page — it is\n// always present, even on the last page — and pass it back next sync for only what changed.\nlet cursor: string | undefined;\ndo {\n  const page = await wf.unwrap(\n    wf.raw.listCompanyInvestmentChanges({ path: { company_id: companyId }, query: { cursor, per_page: 50 } }),\n  );\n  for (const record of page.data ?? []) console.log(record.id, record.visible);\n  cursor = page.meta?.next_cursor;\n  if (!page.meta?.has_more) break;\n} while (cursor);",
+    "listCompanyQuestions": "const page = await wf.unwrap(\n  wf.raw.listCompanyQuestions({\n    path: { id: \"co_abc123Example\" },\n    query: { q: \"revenue\", unanswered_by_team: true, per_page: 20 },\n  }),\n);\nfor (const question of page.data ?? []) console.log(question.id, question.attributes);",
+    "listCompanyUpdates": "const page = await wf.unwrap(wf.raw.listCompanyUpdates({ path: { id: \"co_abc123Example\" }, query: { per_page: 10 } }));\nfor (const update of page.data ?? []) console.log(update.id, update.attributes?.title);\nconsole.log(page.meta?.next_cursor);",
+    "listConnectedApps": "const apps = await wf.unwrap(wf.raw.listConnectedApps());\nfor (const app of apps.data ?? []) {\n  console.log(app.id, app.attributes?.name);\n}",
+    "listEligibleInstallTargets": "const targets = await wf.unwrap(wf.raw.listEligibleInstallTargets({ query: { target_type: \"company\" } }));\nfor (const target of targets.data ?? []) console.log(target);",
+    "listFollowedCompanies": "const page = await wf.unwrap(wf.raw.listFollowedCompanies({ query: { per_page: 25 } }));\nfor (const company of page.data ?? []) console.log(company.id);",
+    "listInstallations": "const installs = await wf.unwrap(wf.raw.listInstallations());\nfor (const install of installs.data ?? []) console.log(install.id, install.attributes);",
+    "listIntents": "// Which of my proposed actions are still waiting on human approval?\nconst page = await wf.intents.list({ status: \"pending\" });\nfor (const intent of page.data ?? []) {\n  console.log(intent.id, intent.attributes?.action, intent.attributes?.review_url);\n}",
+    "listInvestments": "// Auto-paginate the full history lazily:\nfor await (const investment of wf.investments.all()) {\n  console.log(investment.id);\n}\n\n// Or grab one page with its meta (next_cursor, etc.):\nconst page = await wf.investments.list();\nconsole.log(page.data?.length, page.meta?.next_cursor);",
+    "listMyCompanies": "const companies = await wf.unwrap(wf.raw.listMyCompanies());\nfor (const company of companies.data ?? []) console.log(company.id, company.attributes?.name);",
+    "listOfferings": "// Browse live offerings, sorted. The cursor is opaque and handled for you.\nconst page = await wf.offerings.list({ sort: \"most_raised\" });\nfor (const offering of page.data ?? []) {\n  console.log(offering.id, offering.attributes?.company_name);\n}\n\n// Or stream every offering lazily, one page fetched at a time:\nfor await (const offering of wf.offerings.all({ sort: \"newest\" })) {\n  console.log(offering.id);\n}",
+    "listPortfolioPositions": "for await (const position of wf.portfolio.positions.all({ status: \"active\" })) {\n  console.log(\n    position.id,\n    position.attributes?.company?.name,\n    position.attributes?.current_value_cents,\n  );\n}",
+    "listSyndicatePortfolioPositions": "const page = await wf.unwrap(\n  wf.raw.listSyndicatePortfolioPositions({\n    path: { syndicate_id: \"syn_example\" },\n    query: { status: \"active\", per_page: 25 },\n  }),\n);\nfor (const position of page.data ?? []) {\n  console.log(position.id, position.attributes?.investor_count);\n}",
+    "listSyndicates": "const page = await wf.syndicates.list({ limit: 50 });\nfor (const syndicate of page.data ?? []) {\n  console.log(syndicate.id, syndicate.attributes?.name, syndicate.attributes?.member_count);\n}",
+    "listWebhookEndpoints": "const { data: endpoints, meta } = await wf.webhookEndpoints.list();\nconsole.log(`${endpoints?.length} of ${meta?.quota} endpoint slots used`);\nfor (const ep of endpoints ?? []) {\n  console.log(ep.id, ep.attributes?.url, ep.attributes?.enabled, ep.attributes?.last_delivery_status);\n}",
+    "listWebhookSubscriptions": "const subscriptions = await wf.unwrap(\n  wf.raw.listWebhookSubscriptions({ path: { campaign_id: 1234 } }),\n);\nfor (const sub of subscriptions.data ?? []) {\n  console.log(sub.id, sub.target_url, sub.events, sub.active);\n}",
+    "previewIntent": "const preview = await wf.unwrap(\n  wf.raw.previewIntent({\n    body: {\n      action_name: \"syndicates.close_deal\",\n      resource_type: \"Club\",\n      resource_id: \"syn_example\",\n      params: { fundraise_id: 99 },\n    },\n  }),\n);\nconsole.log(preview);",
+    "reenableWebhookEndpoint": "const endpoint = await wf.webhookEndpoints.reenable(\"whe_8f3ExampleEndpoint00\");\nconsole.log(endpoint.attributes?.enabled); // true",
+    "revokeInstallation": "const result = await wf.unwrap(wf.raw.revokeInstallation({ path: { external_id: \"ins_9t2xExample\" } }));\nconsole.log(result);",
+    "rotateWebhookEndpointSecret": "const endpoint = await wf.webhookEndpoints.rotateSecret(\"whe_8f3ExampleEndpoint00\");\nconst newSecret = endpoint.attributes?.secret; // shown once\nconsole.log(newSecret);",
+    "searchCompanies": "const results = await wf.unwrap(wf.raw.searchCompanies({ query: { q: \"solar\", limit: 5 } }));\nfor (const hit of results.data ?? []) console.log(hit.id, hit.attributes?.name);",
+    "testWebhookEndpoint": "const outcome = await wf.webhookEndpoints.test(\"whe_8f3ExampleEndpoint00\", \"investment.executed\");\nif (outcome.delivered) {\n  console.log(`endpoint answered ${outcome.response_code} in ${outcome.duration_ms}ms`);\n} else {\n  console.log(`no response: ${outcome.error}`); // timeout | blocked_url | tls_error | connection_failed\n}",
+    "testWebhookSubscription": "const result = await wf.unwrap(\n  wf.raw.testWebhookSubscription({ path: { campaign_id: 1234, webhook_id: 56 } }),\n);\nconsole.log(result.data);",
+    "unfollowCompany": "const result = await wf.unwrap(wf.raw.unfollowCompany({ path: { company_id: \"co_abc123Example\" } }));\nconsole.log(result);",
+    "updateWebhookEndpoint": "const endpoint = await wf.webhookEndpoints.update(\"whe_8f3ExampleEndpoint00\", {\n  events: [\"offering.opened\", \"offering.closed\", \"investment.executed\"],\n});\nconsole.log(endpoint.attributes?.events);"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wefunder/sdk",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.10",
   "description": "Official TypeScript SDK for the Wefunder API (beta)",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -35,29 +35,33 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "examples_manifest.json"
   ],
   "scripts": {
     "generate": "openapi-ts",
     "build": "tsup",
     "typecheck": "tsc --noEmit",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
+    "build:examples": "node scripts/build-examples-manifest.mjs",
+    "build:conformance": "node scripts/build-conformance-manifest.mjs",
+    "version": "npm run build:examples && git add examples_manifest.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "vitest run --config vitest.config.e2e.ts",
     "sync-spec": "node scripts/sync-spec.mjs",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
-  },
-  "dependencies": {
-    "@hey-api/client-fetch": "^0.13.1"
+    "prepublishOnly": "npm run typecheck && npm run typecheck:examples && npm test && npm run build"
   },
   "devDependencies": {
-    "@hey-api/openapi-ts": "^0.64.0",
+    "@hey-api/openapi-ts": "^0.99.0",
     "@types/node": "^22.0.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
+    "vitest": "^4.1.9",
+    "prettier": "^3.3.0"
   }
 }