diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index e638be4..d0762d6 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -172,7 +172,9 @@ in only after reading its terms, and only on a deployment whose callers you trust: the daily caps (200 answers per caller, 500 upstream calls per provider) and the 5-minute shared cache are per process, and a caller is the address `clientKey()` sees. The public preview runs no broker, so it uses no house key; -turning one on there is an owner decision under this checklist. +turning one on there is an owner decision under this checklist. FRED's terms require +every app other people use to show its notice and a link to its API terms; each +FRED block and the FRED install review do (`attribution` in `curatedApis.ts`). ### Connect (OAuth sign-in) diff --git a/src/blocks/capability/CapabilityBlock.tsx b/src/blocks/capability/CapabilityBlock.tsx index f98b19c..963530c 100644 --- a/src/blocks/capability/CapabilityBlock.tsx +++ b/src/blocks/capability/CapabilityBlock.tsx @@ -15,6 +15,8 @@ import { EffectPill } from '@/components/apis/ApiReview'; import { KeyField, keySlotOf, useHasKey, useHouseKeyCovers } from '@/components/apis/KeyField'; import { useRememberingKeys } from '@/components/apis/RememberKeys'; import { SignInPrompt, useSignIn } from '@/components/apis/SignIn'; +import { ProviderAttribution } from '@/components/apis/ProviderAttribution'; +import { attributionFor } from '@/core/capabilities/curatedApis'; import { argumentsFrom, CapabilityInputs, constantOf, inputSummaryOf, missingInputs } from './CapabilityInputs'; import { CapabilityResult } from './CapabilityResult'; @@ -97,6 +99,8 @@ export function CapabilityBlockView({ instanceId }: { instanceId: string }) { const signIn = useSignIn(manifest); const needsSignIn = signIn !== null && !signIn.signedIn; const needsCredential = needsKey || needsSignIn; + // A provider whose terms require a notice on every app screen that uses it (FRED). + const attribution = attributionFor(manifest); const sideEffect = manifest?.effect === 'write' || manifest?.effect === 'destructive'; const params = isPlainParams(block?.params) ? block.params : {}; @@ -271,6 +275,7 @@ export function CapabilityBlockView({ instanceId }: { instanceId: string }) {

) : null} + {attribution ? : null} {previewError ? (

{previewError}

) : null} diff --git a/src/blocks/capability/ProviderAttribution.component.test.tsx b/src/blocks/capability/ProviderAttribution.component.test.tsx new file mode 100644 index 0000000..0a052e7 --- /dev/null +++ b/src/blocks/capability/ProviderAttribution.component.test.tsx @@ -0,0 +1,51 @@ +// @vitest-environment happy-dom +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { render, screen } from '@testing-library/react'; +import { CapabilityBlockView } from './CapabilityBlock'; +import { attributionFor, curatedApi } from '@/core/capabilities/curatedApis'; +import { compileOpenApi } from '@/core/capabilities/openapi'; +import { clearCapabilities, installProposal } from '@/core/capabilities/registry'; +import { blockRegistry } from '@/core/registry/BlockRegistry'; +import { useBlockStore, useWireStore } from '@/core/stores'; + +const NOTICE = 'This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.'; + +function fredManifests() { + const fred = curatedApi('omni:fred')!; + return compileOpenApi(fred.spec, { sourceLocator: fred.entry.specUrl, brokerOrigins: fred.brokerOrigins }).manifests; +} + +beforeEach(() => { + clearCapabilities(); + useBlockStore.setState({ blocks: [], activeShellId: 'root' }); + useWireStore.setState({ wires: [] }); +}); +afterEach(() => { + clearCapabilities(); + useBlockStore.setState({ blocks: [] }); +}); + +describe('FRED attribution', () => { + it('applies to every FRED operation, by its origin, however it was installed', () => { + for (const manifest of fredManifests()) expect(attributionFor(manifest)?.notice).toBe(NOTICE); + const pasted = compileOpenApi(curatedApi('omni:fred')!.spec).manifests[0]; + expect(attributionFor(pasted)?.notice).toBe(NOTICE); + }); + + it('does not apply to other APIs', () => { + const metaculus = curatedApi('omni:metaculus')!; + const [manifest] = compileOpenApi(metaculus.spec, { brokerOrigins: metaculus.brokerOrigins }).manifests; + expect(attributionFor(manifest)).toBeNull(); + }); + + it('shows the notice and the terms link on a FRED block, before any run', () => { + const [manifest] = fredManifests(); + expect(installProposal(manifest).ok).toBe(true); + const instanceId = useBlockStore.getState().addBlock(blockRegistry.get(manifest.id)!, { x: 0, y: 0 }); + render(); + expect(screen.getByTestId('provider-attribution').textContent).toContain(NOTICE); + const link = screen.getByRole('link', { name: 'FRED® API Terms of Use' }) as HTMLAnchorElement; + expect(link.href).toBe('https://fred.stlouisfed.org/docs/api/terms_of_use.html'); + expect(link.rel).toContain('noopener'); + }); +}); diff --git a/src/components/apis/AddApiDialog.component.test.tsx b/src/components/apis/AddApiDialog.component.test.tsx index c7ead92..6f9dd3d 100644 --- a/src/components/apis/AddApiDialog.component.test.tsx +++ b/src/components/apis/AddApiDialog.component.test.tsx @@ -114,6 +114,8 @@ describe('AddApiDialog: a curated API (FRED)', () => { expect(await screen.findByText(/Spec written by Flyspace from the provider/)).toBeTruthy(); expect(screen.getByText(/Sends requests to/).textContent).toContain('https://api.stlouisfed.org through Flyspace’s own server'); expect(screen.getByText(/refuses calls from a browser/)).toBeTruthy(); + // FRED's terms: its notice and terms link, shown before installing. + expect(screen.getByTestId('provider-attribution').textContent).toContain('is not endorsed or certified by the Federal Reserve Bank of St. Louis'); // Where to get the key, from FRED's own pages, and the documented format checked on paste. const guide = screen.getByTestId('key-guide'); expect(guide.textContent).toContain('Get a key at fredaccount.stlouisfed.org/apikeys'); diff --git a/src/components/apis/AddApiDialog.tsx b/src/components/apis/AddApiDialog.tsx index 8b44e44..27e691e 100644 --- a/src/components/apis/AddApiDialog.tsx +++ b/src/components/apis/AddApiDialog.tsx @@ -5,7 +5,7 @@ import { X } from 'lucide-react'; import { ApiSearch } from '@/components/ApiSearch'; import type { ApiIndexEntry } from '@/core/capabilities/apiIndex'; import { compileOpenApi } from '@/core/capabilities/openapi'; -import { curatedApi } from '@/core/capabilities/curatedApis'; +import { attributionFor, curatedApi } from '@/core/capabilities/curatedApis'; import { checkKeyFormat, keyGuideFor } from '@/core/capabilities/keyGuide'; import { KeyGuideNote } from './KeyGuideNote'; import { useKeyKeepingNote } from './RememberKeys'; @@ -19,6 +19,7 @@ import { spatialSession } from '@/core/interaction/session'; import { useUIStore } from '@/core/stores/uiStore'; import { ApiReview, destinationOf } from './ApiReview'; import { isUserInstalled, YourApis } from './YourApis'; +import { ProviderAttribution } from './ProviderAttribution'; /** A capability block's default footprint, used to center it on the canvas. */ const BLOCK_SIZE = { width: 320, height: 240 }; @@ -311,6 +312,10 @@ export function AddApiDialog({ open, onClose }: AddApiDialogProps) { ) : null} + {(() => { + const attribution = proposals.map(attributionFor).find(Boolean); + return attribution ? : null; + })()} {proposals.some(manifest => install[manifest.id] && manifest.auth.kind === 'oauth') ? (

These operations read your own account, so they need a sign-in with read-only access. Place them, then sign in from the block. diff --git a/src/components/apis/ProviderAttribution.tsx b/src/components/apis/ProviderAttribution.tsx new file mode 100644 index 0000000..526c845 --- /dev/null +++ b/src/components/apis/ProviderAttribution.tsx @@ -0,0 +1,19 @@ +'use client'; + +import type { Attribution } from '@/core/capabilities/curatedApis'; + +/** + * What a provider's terms require an app to show (FRED's notice and terms + * link), in the provider's own words. Not collapsible: the terms ask for it + * to be shown prominently. + */ +export function ProviderAttribution({ attribution }: { attribution: Attribution }) { + return ( +

+ {attribution.notice} Using this block means agreeing to the{' '} + + {attribution.termsTitle} + . +

+ ); +} diff --git a/src/core/capabilities/curatedApis.ts b/src/core/capabilities/curatedApis.ts index 38d17b1..a07b934 100644 --- a/src/core/capabilities/curatedApis.ts +++ b/src/core/capabilities/curatedApis.ts @@ -5,6 +5,7 @@ import type { ApiIndexEntry } from './apiIndex'; import type { KeyGuide } from './keyGuide'; +import type { CapabilityManifest } from './manifest'; import { ALPHA_VANTAGE_SPEC } from './curated/alphaVantage'; import { BLS_SPEC } from './curated/bls'; import { FRED_SPEC } from './curated/fred'; @@ -20,6 +21,16 @@ export interface CuratedApi { keyGuide?: Omit; /** The environment variable the quality line reads its key from (scripts/verify-curated.ts). */ keyEnv?: string; + /** What the provider's terms require an app to show its users, on every block that calls it. */ + attribution?: Attribution; +} + +export interface Attribution { + /** The provider's own wording, shown as written. */ + notice: string; + /** The terms a person agrees to by using the block. */ + termsUrl: string; + termsTitle: string; } export const CURATED_APIS: readonly CuratedApi[] = [ @@ -46,7 +57,15 @@ export const CURATED_APIS: readonly CuratedApi[] = [ format: { pattern: '^[a-z0-9]{32}$', describe: '32 lowercase letters and digits' }, test: { operationId: 'getSeriesObservations', input: { series_id: 'GDP', file_type: 'json', limit: 1 } } }, - brokerOrigins: ['https://api.stlouisfed.org'] + brokerOrigins: ['https://api.stlouisfed.org'], + // Required by https://fred.stlouisfed.org/docs/api/terms_of_use.html (checked 2026-10-12) + // for an application other people use: this exact notice, shown prominently, and a link to + // the terms that using the application means agreeing to. + attribution: { + notice: 'This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.', + termsUrl: 'https://fred.stlouisfed.org/docs/api/terms_of_use.html', + termsTitle: 'FRED® API Terms of Use' + } }, { entry: { @@ -143,6 +162,22 @@ export const CURATED_APIS: readonly CuratedApi[] = [ } ]; +/** + * The attribution a provider's terms require, for any manifest that calls it, + * however it was installed: matched on the API's origin, not the install path. + */ +export function attributionFor(manifest: CapabilityManifest | undefined): Attribution | null { + if (!manifest || manifest.transport.kind !== 'http') return null; + let origin: string; + try { + origin = new URL(manifest.transport.baseUrl).origin; + } catch { + return null; + } + const api = CURATED_APIS.find(entry => entry.attribution && entry.brokerOrigins.includes(origin)); + return api?.attribution ?? null; +} + export function curatedApi(id: string): CuratedApi | undefined { return CURATED_APIS.find(api => api.entry.id === id); }