Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
5 changes: 5 additions & 0 deletions src/blocks/capability/CapabilityBlock.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down Expand Up @@ -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 : {};
Expand Down Expand Up @@ -271,6 +275,7 @@ export function CapabilityBlockView({ instanceId }: { instanceId: string }) {
</p>
) : null}
</div>
{attribution ? <ProviderAttribution attribution={attribution} /> : null}
{previewError ? (
<p className="text-xs text-[var(--truth-red)]">{previewError}</p>
) : null}
Expand Down
51 changes: 51 additions & 0 deletions src/blocks/capability/ProviderAttribution.component.test.tsx
Original file line number Diff line number Diff line change
@@ -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(<CapabilityBlockView instanceId={instanceId} />);
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');
});
});
2 changes: 2 additions & 0 deletions src/components/apis/AddApiDialog.component.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
7 changes: 6 additions & 1 deletion src/components/apis/AddApiDialog.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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 };
Expand Down Expand Up @@ -311,6 +312,10 @@ export function AddApiDialog({ open, onClose }: AddApiDialogProps) {
<ul className="mt-1 space-y-0.5">{review.issues.map(issue => <li key={issue}>{issue}</li>)}</ul>
</details>
) : null}
{(() => {
const attribution = proposals.map(attributionFor).find(Boolean);
return attribution ? <ProviderAttribution attribution={attribution} /> : null;
})()}
{proposals.some(manifest => install[manifest.id] && manifest.auth.kind === 'oauth') ? (
<p className="text-xs text-[var(--text-muted)]">
These operations read your own account, so they need a sign-in with read-only access. Place them, then sign in from the block.
Expand Down
19 changes: 19 additions & 0 deletions src/components/apis/ProviderAttribution.tsx
Original file line number Diff line number Diff line change
@@ -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 (
<p data-testid="provider-attribution" className="text-[10px] leading-snug text-[var(--text-secondary)]">
{attribution.notice} Using this block means agreeing to the{' '}
Comment thread
claude[bot] marked this conversation as resolved.
Resolved
<a href={attribution.termsUrl} target="_blank" rel="noopener noreferrer" className="underline">
{attribution.termsTitle}
</a>.
</p>
);
}
37 changes: 36 additions & 1 deletion src/core/capabilities/curatedApis.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -20,6 +21,16 @@ export interface CuratedApi {
keyGuide?: Omit<KeyGuide, 'source'>;
/** 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[] = [
Expand All @@ -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: {
Expand Down Expand Up @@ -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);
}
Loading