Proxy Methods

Fetch external content through the TelemetryOS proxy service with built-in fleet-wide caching.

Overview

The Proxy Methods let you fetch data from any external API or URL. Requests are routed through the TelemetryOS platform, which automatically handles CORS restrictions and caches responses across your entire device fleet.

You can call proxy().fetch() and use the response directly -- the platform handles caching for you. There is no need to build your own caching layer using the store or other mechanisms.

About CORS: TelemetryOS applications run in browser contexts where Cross-Origin Resource Sharing (CORS) policies apply. The Proxy API solves CORS limitations by routing requests through the TelemetryOS platform. For complete CORS information, see Understanding CORS.

Importing

import { proxy } from '@telemetryos/sdk';

Methods

fetch()

Fetch content from external URLs through the platform proxy.

Signature:

async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>

Parameters:

• input - URL as string, URL object, or Request object
• init - Optional fetch options (method, headers, body, etc.)

Returns: Promise<Response> - Standard Response object

Example:

const response = await proxy().fetch('https://query1.finance.yahoo.com/v8/finance/chart/AAPL?interval=1d&range=5d');
const data = await response.json();

// Use the data directly - the platform caches it for you
console.log(data.chart.result[0].meta.regularMarketPrice);

Caching Behavior

The proxy includes built-in fleet-wide caching. When any device in your fleet fetches a URL, the response is cached on the platform so that subsequent requests from other devices are served from cache. You do not need to implement any caching logic in your application.

How It Works

1. Device calls proxy().fetch() -- the request is sent to the TelemetryOS platform
2. Platform checks its cache -- a two-tier cache (in-memory + database) looks for a valid cached response
3. Cache hit: the cached response is returned immediately without contacting the external server
4. Cache miss: the platform fetches from the external server, caches the response, and returns it

Because the cache is shared across your entire fleet, even if you have hundreds or thousands of devices requesting the same URL, the external server typically sees only one request per cache period. This prevents rate limiting and reduces bandwidth usage.

Default Caching

• GET requests: Cached for 60 seconds by default
• Other methods (POST, PUT, DELETE, PATCH): Not cached. Successful unsafe methods automatically invalidate the cache for that URL.

Cache Revalidation

The platform supports ETag and Last-Modified revalidation. When a cached response includes these headers, the platform sends conditional requests (If-None-Match / If-Modified-Since) to the upstream server. If the content hasn't changed, the server responds with 304 Not Modified and the cached response is reused -- saving bandwidth across your fleet.

Controlling Cache with Headers

Control proxy caching using standard Cache-Control request headers:

// Force fresh fetch (bypass cache)
const response = await proxy().fetch('https://query1.finance.yahoo.com/v8/finance/chart/AAPL', {
  headers: { 'Cache-Control': 'no-cache' }
});

// Cache for 5 minutes
const response = await proxy().fetch('https://query1.finance.yahoo.com/v8/finance/chart/AAPL?interval=1d&range=5d', {
  headers: { 'Cache-Control': 'max-age=300' }
});

Supported directives:

• no-cache -- bypass cache, always fetch fresh
• no-store -- never cache the response
• max-age=<seconds> -- set a custom cache duration

The proxy also respects Cache-Control headers from the upstream server. If the server includes max-age, no-store, or private, those directives take precedence over the default TTL.

Next Steps

• Understanding CORS - Learn about CORS and why Proxy is needed
• Weather Methods - Weather data through the built-in TelemetryOS API (no proxy needed)
• Code Examples - Complete proxy integration examples