Monetzly server SDK quickstart

1. Install

npm install @monetzly/server-sdk

The package is server-side only. It talks to the Monetzly ad service over gRPC and holds your API key, so it must never be bundled into client code.

2. Configure the client

Create the client once at module scope so the connection is reused across requests, rather than per invocation.

import { MonetzlySDK, MonetzlyConfig } from "@monetzly/server-sdk";

const config: MonetzlyConfig = {
  apiKey: process.env.MONETZLY_API_KEY!,
  serverAddress: process.env.MONETZLY_SERVER_ADDRESS!, // host:port
  useSSL: true,
  timeout: 30000,
};

export const sdk = new MonetzlySDK(config);

Environment variables

MONETZLY_API_KEY=mz_live_...
MONETZLY_SERVER_ADDRESS=ads.monetzly.com:443

3. Wrap your response stream

Call connect() before the first injection, then pass your model's token stream through inject(). It accepts an AsyncIterable or a ReadableStream of chunks and returns an async generator of the same chunk shape, so your existing forwarding loop is unchanged.

await sdk.connect();

const llmStream = await llm.stream(messages);

for await (const chunk of sdk.inject(llmStream, {
  sessionId,                          // stable per conversation
  metadata: { app: "my-assistant" },  // optional, per-call
})) {
  const text = chunk.text ?? chunk.content ?? "";
  if (text) controller.enqueue(encoder.encode(text));
}

4. Non-streaming responses

If your endpoint returns a single completion rather than a stream, wrap the completion in a one-chunk async iterable and concatenate the result.

async function* once(text: string) {
  yield { text };
}

let out = "";
for await (const chunk of sdk.inject(once(completion.text), { sessionId })) {
  out += chunk.text ?? chunk.content ?? "";
}
return out;

5. Fail open, always

Monetization must never be able to break the product. Treat the ad layer as optional and fall back to the unmodified stream on any error.

let stream: AsyncIterable<{ text?: string; content?: string }> = llmStream;
try {
  await sdk.connect();
  stream = sdk.inject(llmStream, { sessionId });
} catch (err) {
  console.error("monetzly unavailable — streaming unmodified response", err);
}

for await (const chunk of stream) {
  /* forward exactly as before */
}

• Keep timeout tight relative to your own latency budget, so a slow match can never delay the first token.
• Log fallbacks with a counter you can alert on — silent degradation looks like zero revenue with no cause.
• isConfigured() tells you whether the client has usable credentials; use it to skip injection entirely in environments without a key.

6. Controls you own

• Category blocks — exclude competitors, regulated goods, or anything off-brand. Configured per app during onboarding.
• Sensitive-context suppression — health, finance, legal and anything involving minors default to no placements.
• Frequency caps — placements per session are capped independently of how many turns would technically qualify.
• Per-turn suppression — skip injection on turns where advice quality matters more than revenue by streaming the original stream directly.

Sponsored elements are always labelled as sponsored in the response. That is not configurable, and it is what keeps the format viable.

7. Launch checklist

1. A conversation with clear commercial intent produces a labelled sponsored mention.
2. A conversation with none produces a response byte-identical to the unwrapped version.
3. With the ad service unreachable, responses still stream normally.
4. Impressions and clicks appear against the sessionId you passed.
5. Your API key is absent from client bundles (grep the build output).
6. Category blocks and sensitive-context rules match what your app actually serves.

Framework-specific guides