soundcloud-api-ts-next
    Preparing search index...

    Interface SoundCloudRoutesConfig

    Configuration for initializing server-side SoundCloud API route handlers.

    import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";

    const sc = createSoundCloudRoutes({
      clientId: process.env.SC_CLIENT_ID!,
      clientSecret: process.env.SC_CLIENT_SECRET!,
      redirectUri: "http://localhost:3000/api/soundcloud/auth/callback",
    });

    createSoundCloudRoutes for usage

    interface SoundCloudRoutesConfig {
        cache?: SoundCloudCache;
        cacheHeaders?: { [routePrefix: string]: string };
        cacheTtlMs?: number;
        clientId: string;
        clientSecret: string;
        cors?: { methods?: string[]; origin?: string | string[] };
        csrfProtection?: boolean;
        dedupe?: boolean;
        fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
        getToken?: () => Promise<string>;
        maxRetries?: number;
        onRequest?: (telemetry: SCRequestTelemetry) => void;
        onRetry?: (info: RetryInfo) => void;
        onRouteComplete?: (telemetry: SCRouteTelemetry) => void;
        redirectUri?: string;
        retryBaseDelay?: number;
        routes?: { allowlist?: string[]; denylist?: string[] };
    }
    Index

    Properties

    cache? cacheHeaders? cacheTtlMs? clientId clientSecret cors? csrfProtection? dedupe? fetch? getToken? maxRetries? onRequest? onRetry? onRouteComplete? redirectUri? retryBaseDelay? routes?

    Properties

    cache?: SoundCloudCache

    Optional cache backend for GET responses on the underlying client. Implement the SoundCloudCache interface to plug in any backend (in-memory, Redis, etc.).

    cacheHeaders?: { [routePrefix: string]: string }

    Set Cache-Control headers on GET responses, keyed by route prefix. Use "default" as a fallback for unmatched prefixes.

    cacheHeaders: { tracks: "public, max-age=60", me: "no-store", default: "public, max-age=30" }
    cacheTtlMs?: number

    Default TTL in milliseconds for cached GET responses (used with cache).

    60000
    clientId: string

    SoundCloud OAuth client ID from your app registration.

    clientSecret: string

    SoundCloud OAuth client secret from your app registration.

    cors?: { methods?: string[]; origin?: string | string[] }

    CORS configuration. When set, Access-Control-Allow-Origin and Access-Control-Allow-Methods headers are added to responses.

    Type Declaration

    • Optionalmethods?: string[]

      Allowed HTTP methods (default: inherited from your route exports).

    • Optionalorigin?: string | string[]

      Allowed origin(s). Pass a string or array of strings.

    cors: { origin: "https://myapp.com", methods: ["GET", "POST", "DELETE"] }
    csrfProtection?: boolean

    When true, POST/DELETE mutation routes (like, repost, follow) require a matching Origin header. If cors.origin is also set, the Origin must match an allowed origin. Helps prevent CSRF on action endpoints. Default: false.

    dedupe?: boolean

    Deduplicate concurrent identical GET requests on the underlying client (concurrent callers share one promise and receive the same object reference).

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

    Custom fetch implementation forwarded to the underlying SoundCloudClient. Useful for Workers/Bun/Deno portability or test injection.

    Type Declaration

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

      • MDN Reference

        Parameters

        • input: RequestInfo | URL
        • Optionalinit: RequestInit

        Returns Promise<Response>

    globalThis.fetch
    getToken?: () => Promise<string>

    Custom token provider for public (non-auth) routes. When set, this function is called instead of the default client-credentials flow. Useful when your app stores OAuth tokens externally (e.g. Redis, database).

    Type Declaration

      • (): Promise<string>

      • Returns Promise<string>

        A valid SoundCloud access token string.

    const sc = createSoundCloudRoutes({
      clientId: process.env.SC_CLIENT_ID!,
      clientSecret: process.env.SC_CLIENT_SECRET!,
      getToken: async () => {
        const redis = await getRedisClient();
        return redis.get("sc:token");
      },
    });
    maxRetries?: number

    Maximum number of retries on 429 (rate limit) and 5xx (server error) responses.

    3
    onRequest?: (telemetry: SCRequestTelemetry) => void

    Passed through to the underlying SoundCloud API calls for per-request telemetry. Fires for each individual SoundCloud API request (including retries).

    const sc = createSoundCloudRoutes({
      clientId: process.env.SC_CLIENT_ID!,
      clientSecret: process.env.SC_CLIENT_SECRET!,
      onRequest: (t) => console.log(`[SC] ${t.method} ${t.path} ${t.status} ${t.durationMs}ms`),
    });
    onRetry?: (info: RetryInfo) => void

    Called before each retry attempt on the underlying client with structured retry info (attempt, delay, reason, status, url).

    onRouteComplete?: (telemetry: SCRouteTelemetry) => void

    Called after every API route is handled with route-level telemetry. Use for logging, metrics, or observability on the Next.js side.

    const sc = createSoundCloudRoutes({
      clientId: process.env.SC_CLIENT_ID!,
      clientSecret: process.env.SC_CLIENT_SECRET!,
      onRouteComplete: (t) => console.log(`[Route] ${t.method} ${t.route} ${t.status} ${t.durationMs}ms`),
    });
    redirectUri?: string

    OAuth redirect URI — required if using authentication features (login/callback).

    retryBaseDelay?: number

    Base delay in milliseconds for exponential backoff between retries.

    1000
    routes?: { allowlist?: string[]; denylist?: string[] }

    Selective route exposure. Use allowlist to only expose specific route prefixes, or denylist to block specific ones. Unlisted routes return 403 when allowlist is set.

    Type Declaration

    • Optionalallowlist?: string[]

      Only expose these route prefixes (e.g. ["tracks", "search"]).

    • Optionaldenylist?: string[]

      Block these route prefixes (e.g. ["me", "likes"]).

    routes: { allowlist: ["tracks", "search", "resolve"] }
    routes: { denylist: ["me", "auth"] }

    Settings

    Member Visibility

    On This Page

    Properties