@stackline/sse 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes are documented in this file.
 
+## [1.0.1] - 2026-08-21
+
+### Added
+
+- Executable local stream, parser, OpenAI Responses, Anthropic Messages, and
+  edge-handler examples.
+- Integration recipes for provider streams, browsers, Node.js, Workers, and
+  low-change package aliases.
+- Reproducible parser, encoder, and adversarial-fragmentation methodology.
+- First-party documentation analytics that never records stream contents.
+- Trusted-publishing workflow for provenance-enabled future releases.
+
+### Changed
+
+- Package tarballs now include the public guides and examples.
+
+No runtime API or declaration behavior changed in this release.
+
 ## [1.0.0] - 2026-08-16
 
 ### Added
@@ -20,3 +38,4 @@ All notable changes are documented in this file.
 - Request header preservation when adding SSE negotiation and resume headers.
 
 [1.0.0]: https://github.com/alexandroit/stackline-sse/releases/tag/v1.0.0
+[1.0.1]: https://github.com/alexandroit/stackline-sse/compare/v1.0.0...v1.0.1

package/README.md

@@ -335,6 +335,16 @@ TypeScript 3.9, 4.7, 4.9, 5.x, 6.x, and 7.x.
 See [SECURITY.md](SECURITY.md) for vulnerability reporting and
 [CONTRIBUTING.md](CONTRIBUTING.md) for development instructions.
 
+## Adoption resources
+
+- [OpenAI, Anthropic, browser, Node.js, and edge recipes](docs/INTEGRATIONS.md)
+- [Reproducible parser and fragmentation benchmarks](docs/BENCHMARKS.md)
+- [Executable examples](examples)
+- [Stackline open-source catalog](https://alexandro.net/docs/open-source/)
+
+The examples ship in the npm tarball. Network examples expose functions and do
+not send requests during installation or import.
+
 ## License
 
 [MIT](LICENSE) Copyright 2026 Alexandro Paixao Marques.

package/dist/index.cjs

@@ -1,4 +1,4 @@
-/*! @stackline/sse v1.0.0 | MIT */
+/*! @stackline/sse v1.0.1 | MIT */
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/index.js

@@ -1,4 +1,4 @@
-/*! @stackline/sse v1.0.0 | MIT */
+/*! @stackline/sse v1.0.1 | MIT */
 
 // src/errors.js
 var SSEError = class extends Error {

package/dist/index.min.js

@@ -1,4 +1,4 @@
-/*! @stackline/sse v1.0.0 | MIT */
+/*! @stackline/sse v1.0.1 | MIT */
 var StacklineSSE=(()=>{var Le=Object.defineProperty;var Ze=Object.getOwnPropertyDescriptor;var Ge=Object.getOwnPropertyNames;var et=Object.prototype.hasOwnProperty;var tt=(e,t)=>{for(var r in t)Le(e,r,{get:t[r],enumerable:!0})},rt=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of Ge(t))!et.call(e,a)&&a!==r&&Le(e,a,{get:()=>t[a],enumerable:!(n=Ze(t,a))||n.enumerable});return e};var nt=e=>rt(Le({},"__esModule",{value:!0}),e);var Ut={};tt(Ut,{EVENT_STREAM_CONTENT_TYPE:()=>U,EventStreamContentType:()=>ye,SSEEncodeError:()=>g,SSEError:()=>_,SSEHTTPError:()=>H,SSEParseError:()=>O,SSEReplayError:()=>q,SSERetryError:()=>J,SSETimeoutError:()=>M,consumeSSE:()=>le,createDecoderStream:()=>Re,createEncoderStream:()=>be,createParser:()=>G,createSSEChannel:()=>Ae,decodeJSON:()=>Te,decodeSSE:()=>ee,default:()=>Mt,encode:()=>Se,encodeComment:()=>we,encodeJSON:()=>W,encodeSSE:()=>D,eventStreamResponse:()=>Ne,fetchEventSource:()=>_e,fetchSSE:()=>de,toAsyncIterable:()=>fe});var _=class extends Error{constructor(t,r,n){super(t),this.name=new.target.name,this.code=r,n&&n.cause!==void 0&&(this.cause=n.cause)}},O=class extends _{constructor(t,r={}){super(t,r.code||"ERR_SSE_PARSE",r),this.fatal=r.fatal===!0,r.field!==void 0&&(this.field=r.field),r.line!==void 0&&(this.line=r.line),r.limit!==void 0&&(this.limit=r.limit)}},g=class extends _{constructor(t,r,n){super(t,"ERR_SSE_ENCODE",{cause:n}),this.field=r}},H=class extends _{constructor(t,r,n="ERR_SSE_HTTP"){super(t,n),this.response=r,this.status=r&&typeof r.status=="number"?r.status:0}},M=class extends _{constructor(t,r,n){super(`SSE ${t} timeout after ${r}ms`,"ERR_SSE_TIMEOUT",{cause:n}),this.phase=t,this.timeout=r}},J=class extends _{constructor(t,r){super(`SSE retry budget exhausted after ${t} attempt${t===1?"":"s"}`,"ERR_SSE_RETRY",{cause:r}),this.attempts=t}},q=class extends _{constructor(){super("The request body cannot be replayed. Provide bodyFactory or disable reconnection.","ERR_SSE_BODY_REPLAY")}};var ot=1024*1024,at=1024*1024,he=10,Fe=13,Z=32,it=65279,De="\0",ce=()=>{};function G(e={}){if(typeof e=="function"&&(e={onEvent:e}),!e||typeof e!="object")throw new TypeError("Parser configuration must be an object or event callback");let t=typeof e.onEvent=="function"?e.onEvent:ce,r=typeof e.onComment=="function"?e.onComment:ce,n=typeof e.onRetry=="function"?e.onRetry:ce,a=typeof e.onError=="function"?e.onError:ce,i=typeof e.onId=="function"?e.onId:ce,f=e.strict===!0,m=e.fatalUTF8===!0,u=$e(e.maxEventSize===void 0?e.maxBufferSize:e.maxEventSize,ot,"maxEventSize"),y=$e(e.maxLineLength,at,"maxLineLength"),p,l,T=[],h=0,S=!1,v=!0,I=[],A=0,w,E=ke(e.lastEventId),b=E,x=!1,L=!1,F=0,d=0,$=0,B=0,ae=0;function P(o){if(L)throw new O("Parser is terminated; call reset() before feeding more data",{code:"ERR_SSE_TERMINATED",fatal:!0});if(typeof o=="string"){if(l==="bytes")throw j("Cannot mix string and byte chunks in one parser stream","ERR_SSE_CHUNK_TYPE");return l="string",d+=o.length,ie(o),ne}if(!(o instanceof Uint8Array))throw new TypeError("SSE parser chunks must be strings or Uint8Array values");if(l==="string")throw j("Cannot mix string and byte chunks in one parser stream","ERR_SSE_CHUNK_TYPE");l="bytes",F+=o.byteLength;let c;try{c=Xe().decode(o,{stream:!0})}catch(s){throw s instanceof O?s:j("Invalid UTF-8 in the SSE stream","ERR_SSE_UTF8",{cause:s})}return d+=c.length,ie(c),ne}function K(){if(L)return ne;if(p)try{let o=p.decode();d+=o.length,ie(o)}catch(o){throw j("Invalid UTF-8 at the end of the SSE stream","ERR_SSE_UTF8",{cause:o})}return Qe(),re(),ne}function Oe(o={}){o&&o.consume&&h>0&&N(te());let s=!!(o&&o.preserveLastEventId)?b:ke(e.lastEventId);return p=void 0,l=void 0,T=[],h=0,S=!1,v=!0,I=[],A=0,w=void 0,E=s,b=s,x=!1,L=!1,F=0,d=0,$=0,B=0,ae=0,ne}function ie(o){let c=o;if(v&&c.length>0&&(v=!1,c.charCodeAt(0)===it&&(c=c.slice(1))),c.length===0)return;if(!S&&c.indexOf("\r")===-1){Ee(c);return}let s=0,C=0;for(S&&(S=!1,c.charCodeAt(0)===he&&(s=1,C=1));s<c.length;s++){let R=c.charCodeAt(s);R!==he&&R!==Fe||(Y(c.slice(C,s)),N(te()),re(),R===Fe&&(c.charCodeAt(s+1)===he?s++:s+1===c.length&&(S=!0)),C=s+1)}Y(c.slice(C))}function Ee(o){let c=0,s=o.indexOf(`
 `);for(;s!==-1;){if(h===0&&I.length===0&&o.charCodeAt(s+1)===he&&ft(o,c)){let C=o.charCodeAt(c+5)===Z?c+6:c+5,R=o.slice(C,s);if(s-c>y)throw j(`SSE line exceeded ${y} characters`,"ERR_SSE_LINE_LIMIT",{limit:y});Q(R.length+1),Ke(R),c=s+2,s=o.indexOf(`
 `,c);continue}if(h>0)Y(o.slice(c,s)),N(te()),re();else{if(s-c>y)throw j(`SSE line exceeded ${y} characters`,"ERR_SSE_LINE_LIMIT",{limit:y});N(o.slice(c,s))}c=s+1,s=o.indexOf(`

package/docs/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# Architecture
+
+## Goals
+
+`@stackline/sse` treats SSE as one protocol with five composable surfaces:
+
+1. incremental wire parser;
+2. async iterable and TransformStream adapters;
+3. injection-resistant encoder;
+4. reconnecting Fetch client;
+5. backpressure-aware server output.
+
+The runtime has no package dependencies and no Node-specific imports.
+
+## Parser state machine
+
+The parser stores line fragments rather than repeatedly concatenating an
+unterminated line. This keeps one-character chunk fragmentation linear. LF-only
+input uses an `indexOf` fast path; CR and CRLF use the complete state machine.
+
+State is separated into:
+
+- pending line fragments;
+- current data lines and event type;
+- pending ID field;
+- committed `lastEventId`;
+- counters and configured limits.
+
+An ID is committed at a blank line even if the block has no data. Incomplete
+EOF data is discarded as required by the WHATWG algorithm.
+
+## Backpressure
+
+`decodeSSE` reads one source chunk only when the consumer advances its async
+iterator. Large source chunks are admitted in 16 KiB slices and callback bursts
+are bounded. The server iterable helper asks its source for one item per stream
+pull. Push channels expose `send(): boolean` and `ready`.
+
+## Client lifecycle
+
+Each connection attempt owns an AbortController. External cancellation,
+connect timeout, idle timeout, and total timeout converge on that controller.
+Rejected response bodies are cancelled before retry. A user callback failure is
+wrapped as `ERR_SSE_CALLBACK` and is never classified as a network failure.
+Custom Fetch implementations, body factories, and iterators are raced against
+the attempt signal so a non-cooperative adapter cannot hold a timeout open. A
+response that resolves after timeout is cancelled on arrival.
+
+Resume state is advanced only by committed parser IDs. Retry delay precedence
+is HTTP `Retry-After`, server `retry:`, then client exponential backoff.
+
+Streaming request bodies are not replayed. Applications can provide a
+`bodyFactory` to create one body per attempt; the factory receives the attempt
+signal. Headers from a Request input are preserved unless explicitly replaced.
+
+## Encoder boundary
+
+Data and comments can span lines and are encoded one field per line. Event names
+cannot contain CR or LF. IDs also cannot contain NUL, matching the value space
+of `Last-Event-ID`. These checks prevent field and header injection.
+
+## Build outputs
+
+One source graph produces:
+
+- `dist/index.js` for ESM;
+- `dist/index.cjs` for CommonJS;
+- `dist/index.min.js` for browser globals;
+- declarations for old and conditional-export-aware TypeScript versions.
+
+All outputs are generated from the same commit and packed once for release.

package/docs/BENCHMARKS.md

@@ -0,0 +1,20 @@
+# Benchmark Methodology
+
+The checked-in benchmark compares the incremental parser with
+`eventsource-parser@3.1.1` using the same 50,000-event document. It measures a
+single document, 16 KiB chunks, encoding throughput, and an adversarial stream
+split one character at a time.
+
+```bash
+npm ci
+npm run benchmark
+```
+
+Both parsers are warmed before measurement and must produce the expected event
+count. The adversarial case is reported separately because fragmented input is
+a complexity and memory-safety concern, not only a throughput concern.
+
+Results depend on Node.js, CPU, chunk shape, event size, callbacks, and enabled
+limits. Publish the complete command, environment, and raw JSON output. Do not
+compare unlike parser, client, encoder, and server contracts as if they were
+the same operation.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,57 @@
+# Compatibility
+
+## JavaScript runtimes
+
+Parser and encoder APIs require JavaScript ES2018 and `TextDecoder` only when
+byte chunks are used. The declared Node.js floor is 14.17.
+
+Fetch client requirements:
+
+- `fetch` and `AbortController`;
+- a response body exposed as Web Stream or async iterable.
+
+Server helper requirements:
+
+- `ReadableStream` and `TextEncoder`;
+- `Response` when creating HTTP responses.
+
+Node.js 14 and 16 users can inject a Fetch implementation. Parser and encoder
+usage does not require a polyfill.
+
+## TypeScript
+
+CI compiles clean install fixtures with TypeScript 3.9.10, 4.7.4, 4.9.5,
+5.9.3, 6.0.2, and 7.0.2. Declarations avoid requiring DOM library types by
+using structural Fetch and Web Stream interfaces.
+
+## eventsource-parser surface
+
+Supported familiar fields:
+
+- `createParser({ onEvent, onRetry, onComment, onError })`;
+- `feed(chunk)` and `reset({ consume })`;
+- `maxBufferSize` as an alias for the event limit;
+- event `data`, `event`, and `id` fields.
+
+Differences:
+
+- byte chunks are accepted directly;
+- security limits are enabled by default;
+- `lastEventId` is included and ID-only blocks advance resume state;
+- fatal limits throw immediately and terminate the parser.
+- unknown fields and invalid retries call `onError` only with `strict: true`;
+- `maxBufferSize` aliases the accumulated event limit, while line length has a
+  separate `maxLineLength` limit.
+
+## @microsoft/fetch-event-source surface
+
+Supported callback names are `onopen`, `onmessage`, `onclose`, and `onerror`.
+Fetch options, custom methods, headers, bodies, and custom Fetch functions pass
+through. The package does not automatically disconnect when a document becomes
+hidden, so `openWhenHidden` has no behavioral effect.
+
+## Protocol limits
+
+SSE is UTF-8 only. This package does not implement WebSocket framing, HTTP
+server transports, compression, JSON schema validation, or provider-specific
+AI event models.

package/docs/INTEGRATIONS.md

@@ -0,0 +1,46 @@
+# Integration Recipes
+
+## OpenAI Responses
+
+Use `fetchSSE` when the application wants direct control over streamed
+Responses without adding a provider SDK. Pass the bearer token, JSON request,
+finite retry budget, and an idle timeout. See
+[`examples/openai-responses.mjs`](../examples/openai-responses.mjs).
+
+## Anthropic Messages
+
+Anthropic emits named SSE events. Preserve `event.event` alongside the parsed
+JSON payload so message-start, content-block, delta, and stop events remain
+distinguishable. See
+[`examples/anthropic-messages.mjs`](../examples/anthropic-messages.mjs).
+
+## Browser or Node client
+
+`fetchSSE` accepts standard Fetch options plus retry, connect, idle, and total
+timeouts. Node.js 18 and newer provide Fetch. Node.js 14 and 16 can inject a
+compatible implementation with `options.fetch`.
+
+## Cloudflare Workers and edge handlers
+
+Return `eventStreamResponse(events())` from a Fetch-style handler. The helper
+sets the event-stream content type and cache headers while consuming an async
+iterable with backpressure. See
+[`examples/server-edge.mjs`](../examples/server-edge.mjs).
+
+## Existing parser imports
+
+For a staged migration that keeps `eventsource-parser` imports:
+
+```bash
+npm install eventsource-parser@npm:@stackline/sse
+```
+
+For a staged migration that keeps `@microsoft/fetch-event-source` imports:
+
+```bash
+npm install @microsoft/fetch-event-source@npm:@stackline/sse
+```
+
+Commit the changed lockfile and run the complete consumer suite. Compatibility
+aliases reduce source changes but do not remove the need to review documented
+hardening differences and finite retry policies.

package/docs/MARKET_RESEARCH.md

@@ -0,0 +1,84 @@
+# Market Research
+
+Research date: 2026-08-16.
+
+## Decision
+
+The selected need is a unified, safe Server-Sent Events toolkit. SSE is used by
+AI response streaming, live dashboards, notifications, build logs, and edge
+applications. Existing adoption is large, while the common solution remains
+fragmented across parser, polyfill/client, encoder, and custom retry code.
+
+## Download evidence
+
+Counts below come from the public npm downloads API for two fixed 30-day
+windows. They measure package download activity, including CI and transitive
+installs. They are not unique users and must not be treated as a download
+forecast for this package.
+
+| Package | 2026-07-17 to 2026-08-15 | Prior 30 days | Change |
+| --- | ---: | ---: | ---: |
+| `eventsource-parser` | 239,814,210 | 213,287,465 | +12.44% |
+| `eventsource` | 203,093,267 | 176,499,445 | +15.07% |
+| `eventsource-client` | 809,871 | 832,191 | -2.68% |
+| `eventsource-encoder` | 186,321 | 121,896 | +52.85% |
+| `@microsoft/fetch-event-source` | 11,218,110 | 10,963,830 | +2.32% |
+| `eventsource-polyfill` | 757,091 | 749,470 | +1.02% |
+| Combined activity | 455,878,870 | 402,454,297 | +13.27% |
+
+The combined row contains overlap because applications may install several of
+these packages. The overlap is part of the product observation: users often
+need more than one package to cover the protocol lifecycle.
+
+API source examples:
+
+- `https://api.npmjs.org/downloads/point/2026-07-17:2026-08-15/eventsource-parser`
+- `https://api.npmjs.org/downloads/point/2026-07-17:2026-08-15/eventsource`
+- scoped names use URL encoding in the same endpoint.
+
+## Standards and demand signals
+
+- The WHATWG HTML Living Standard defines UTF-8 decoding, CR/LF handling,
+  field processing, resume IDs, reconnect behavior, and HTTP 204 termination.
+- OpenAI documents server-sent events as the transport for streamed Responses.
+- Native browser EventSource cannot send POST bodies or arbitrary auth headers.
+- `@microsoft/fetch-event-source` addresses Fetch flexibility but its published
+  2.0.1 release is five years old at the research date.
+- `eventsource-parser` is current and fast, but intentionally only a parser.
+
+Primary references:
+
+- [WHATWG Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
+- [OpenAI streaming events](https://platform.openai.com/docs/api-reference/responses-streaming)
+- [npm eventsource-parser](https://www.npmjs.com/package/eventsource-parser)
+- [npm eventsource](https://www.npmjs.com/package/eventsource)
+- [npm @microsoft/fetch-event-source](https://www.npmjs.com/package/@microsoft/fetch-event-source)
+
+## Competitor analysis
+
+| Capability | Parser package | EventSource client | Microsoft Fetch client | `@stackline/sse` |
+| --- | --- | --- | --- | --- |
+| Incremental parser | Yes | Dependency | Internal | Yes |
+| Encoder | Separate package | No | No | Yes |
+| Async iterator | Stream adapter | Yes | No | Yes |
+| POST and custom headers | Retrieval-agnostic | Yes | Yes | Yes |
+| Resume after ID-only block | Not exposed | Limited by parser events | Limited | Yes |
+| Default memory limits | Optional | Parser-dependent | No | Yes |
+| Retry-After and jitter | No | Basic reconnect | Custom callback | Yes |
+| Connect, idle, total timeout | No | No | Custom | Yes |
+| Non-replayable body guard | No | No | No | Yes |
+| Safe encoder field validation | Separate | No | No | Yes |
+| Server Response helper | No | No | No | Yes |
+| Runtime dependencies | 0 | 1 | 0 | 0 |
+
+This table describes documented public behavior at the research date. It is not
+a claim that competing projects are unsafe or unsuitable.
+
+## Product thesis
+
+The opportunity is not another EventSource polyfill. It is one standards-based
+protocol toolkit with consistent safety, cancellation, observability hooks,
+backpressure, and migration paths on both sides of the HTTP connection.
+
+Success requires documentation and ecosystem trust. Download volume is a
+market signal, not a guarantee of adoption.

package/docs/RELEASING.md

@@ -0,0 +1,60 @@
+# Releasing
+
+## Preconditions
+
+- `main` is the only development branch.
+- Version, changelog, documentation, and browser metadata agree.
+- Runtime dependencies remain zero or an exception is documented.
+- Local tests, GitHub CI, and CodeQL pass.
+- npm and Verdaccio authentication are verified.
+
+## Release gate
+
+```bash
+npm ci
+npm test
+npm run test:attw
+npm run audit:dependencies
+npm pack --dry-run
+npm run benchmark
+```
+
+## Immutable artifact
+
+Build and pack once. Publish the same bytes everywhere.
+
+```bash
+version="$(node -p "require('./package.json').version")"
+mkdir -p "release/$version"
+npm pack --ignore-scripts --pack-destination "release/$version"
+(cd "release/$version" && sha512sum *.tgz > SHA512SUMS)
+npm sbom --omit=dev --sbom-format cyclonedx > "release/$version/sbom.cdx.json"
+```
+
+Run `scripts/smoke-install.mjs` against the retained tarball.
+
+## Registry sequence
+
+1. Publish the retained tarball to Verdaccio.
+2. Download it anonymously and compare SHA-512.
+3. Smoke install directly and through both documented aliases.
+4. Run `publish.yml` with the expected SHA-512. The trusted workflow rebuilds
+   the reviewed commit and stops unless its tarball is byte-identical.
+5. Let the workflow publish with npm provenance, then download anonymously and
+   compare SHA-512 again.
+6. Verify `latest`, registry signatures, audit output, and package visibility.
+
+Do not rebuild between publications.
+
+## GitHub and documentation
+
+Tag the exact tested commit. Attach tarball, checksum, and CycloneDX SBOM to the
+GitHub release. Deploy only the project documentation directory under
+`/docs/vanilla/sse/`; do not delete unrelated documentation trees. Verify the
+interactive site on desktop and mobile before announcing the release.
+
+## Rollback
+
+npm releases are immutable. Deprecate a defective version with a precise
+message and publish a patch from the last known-good source. Unpublish only for
+a compelling legal or security emergency.

package/examples/ai-client.mjs

@@ -0,0 +1,28 @@
+import { fetchSSE } from '@stackline/sse';
+
+const received = [];
+for await (const event of fetchSSE('https://api.example.com/stream', {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${process.env.API_TOKEN}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({ stream: true }),
+  fetch: async () => ({
+    body: chunks('data: {"delta":"Hello"}\n\ndata: [DONE]\n\n'),
+    headers: { get: (name) => name.toLowerCase() === 'content-type' ? 'text/event-stream' : null },
+    status: 200
+  }),
+  retry: { retries: 0 }
+})) {
+  if (event.data === '[DONE]') break;
+  received.push(JSON.parse(event.data));
+}
+
+console.log(received);
+
+async function* chunks(document) {
+  const bytes = new TextEncoder().encode(document);
+  yield bytes.subarray(0, 13);
+  yield bytes.subarray(13);
+}

package/examples/anthropic-messages.mjs

@@ -0,0 +1,24 @@
+import { fetchSSE } from '@stackline/sse';
+
+export async function* streamAnthropic(prompt, apiKey = process.env.ANTHROPIC_API_KEY) {
+  if (!apiKey) throw new Error('Set ANTHROPIC_API_KEY before calling streamAnthropic');
+
+  for await (const event of fetchSSE('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'anthropic-version': '2023-06-01',
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey
+    },
+    body: JSON.stringify({
+      max_tokens: 1024,
+      messages: [{ role: 'user', content: prompt }],
+      model: 'your-model',
+      stream: true
+    }),
+    idleTimeout: 45_000,
+    retry: { retries: 3 }
+  })) {
+    yield { event: event.event, payload: JSON.parse(event.data) };
+  }
+}

package/examples/openai-responses.mjs

@@ -0,0 +1,18 @@
+import { fetchSSE } from '@stackline/sse';
+
+export async function* streamOpenAI(input, apiKey = process.env.OPENAI_API_KEY) {
+  if (!apiKey) throw new Error('Set OPENAI_API_KEY before calling streamOpenAI');
+
+  for await (const event of fetchSSE('https://api.openai.com/v1/responses', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ model: 'your-model', input, stream: true }),
+    idleTimeout: 45_000,
+    retry: { retries: 3 }
+  })) {
+    yield JSON.parse(event.data);
+  }
+}

package/examples/parser.mjs

@@ -0,0 +1,10 @@
+import { createParser } from '@stackline/sse';
+
+const parser = createParser({
+  onEvent(event) {
+    console.log(event);
+  }
+});
+
+parser.feed('id: 1\ndata: hello\n');
+parser.feed('data: world\n\n');

package/examples/server-edge.mjs

@@ -0,0 +1,10 @@
+import { eventStreamResponse } from '@stackline/sse';
+
+async function* events() {
+  yield { event: 'ready', data: 'connected', id: '1' };
+  yield { event: 'message', data: 'hello', id: '2' };
+}
+
+export function GET() {
+  return eventStreamResponse(events());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackline/sse",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Universal, spec-correct and memory-safe Server-Sent Events toolkit for AI streaming, browsers, servers and edge runtimes",
   "keywords": [
     "sse",
@@ -61,6 +61,8 @@
   },
   "files": [
     "dist",
+    "docs",
+    "examples",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "LICENSE",
@@ -75,10 +77,11 @@
     "clean": "node scripts/clean.mjs",
     "build": "node scripts/build.mjs",
     "lint": "eslint . && node scripts/check-markdown.mjs",
-    "test": "npm run build && npm run lint && npm run test:coverage && npm run test:types && npm run test:package && npm run test:install && npm run test:docs",
+    "test": "npm run build && npm run lint && npm run test:coverage && npm run test:types && npm run test:examples && npm run test:package && npm run test:install && npm run test:docs",
     "test:unit": "node --test --test-reporter=spec test/*.test.mjs",
     "test:coverage": "c8 --all --src src --check-coverage --lines 100 --functions 100 --statements 100 --branches 95 node --test test/parser.test.mjs test/encoder.test.mjs test/iterable.test.mjs test/client.test.mjs test/server.test.mjs test/security.test.mjs",
     "test:types": "node scripts/test-types.mjs",
+    "test:examples": "node examples/parser.mjs && node examples/ai-client.mjs && node examples/server-edge.mjs && node examples/openai-responses.mjs && node examples/anthropic-messages.mjs",
     "test:package": "node --test test/package.test.mjs && node scripts/check-dist.mjs && publint",
     "test:install": "node scripts/smoke-install.mjs",
     "test:docs": "npm run docs:build && node scripts/check-docs.mjs",