soundcloud-api-ts-next 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 twin-paws
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# soundcloud-api-ts-next
+
+React hooks and Next.js API route handlers for the SoundCloud API. Client secrets stay on the server.
+
+Built on top of [`soundcloud-api-ts`](https://github.com/twin-paws/soundcloud-api-ts).
+
+## Install
+
+```bash
+pnpm add soundcloud-api-ts-next soundcloud-api-ts
+```
+
+## Quick Start
+
+### 1. Set up the API route (App Router)
+
+```ts
+// app/api/soundcloud/[...route]/route.ts
+import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";
+
+const sc = createSoundCloudRoutes({
+  clientId: process.env.SC_CLIENT_ID!,
+  clientSecret: process.env.SC_CLIENT_SECRET!,
+});
+
+export const GET = sc.handler();
+```
+
+### 2. Wrap your app with the provider
+
+```tsx
+// app/layout.tsx
+import { SoundCloudProvider } from "soundcloud-api-ts-next";
+
+export default function RootLayout({ children }) {
+  return (
+    <SoundCloudProvider apiPrefix="/api/soundcloud">
+      {children}
+    </SoundCloudProvider>
+  );
+}
+```
+
+### 3. Use hooks in your components
+
+```tsx
+"use client";
+import { useTrackSearch } from "soundcloud-api-ts-next";
+
+export function Search() {
+  const { data, loading, error } = useTrackSearch("lofi beats", { limit: 10 });
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <ul>
+      {data?.map((track) => (
+        <li key={track.id}>{track.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Pages Router Setup
+
+```ts
+// pages/api/soundcloud/[...route].ts
+import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";
+
+const sc = createSoundCloudRoutes({
+  clientId: process.env.SC_CLIENT_ID!,
+  clientSecret: process.env.SC_CLIENT_SECRET!,
+});
+
+export default sc.pagesHandler();
+```
+
+## Hooks
+
+### `useTrackSearch(query: string, options?: { limit?: number })`
+
+Search for tracks. Returns `{ data: SoundCloudTrack[] | null, loading, error }`.
+
+### `useTrack(trackId: string | number)`
+
+Fetch a single track by ID. Returns `{ data: SoundCloudTrack | null, loading, error }`.
+
+### `useUser(userId: string | number)`
+
+Fetch a single user by ID. Returns `{ data: SoundCloudUser | null, loading, error }`.
+
+### `usePlayer(trackId: string | number)`
+
+Manages an HTML5 Audio element for streaming. Returns:
+
+```ts
+{
+  playing: boolean;
+  progress: number;  // current time in seconds
+  duration: number;  // total duration in seconds
+  play(): void;
+  pause(): void;
+  toggle(): void;
+  seek(time: number): void;
+}
+```
+
+## API Routes
+
+The server handler supports these routes:
+
+| Route | Description |
+|---|---|
+| `/search/tracks?q=...&page=...` | Search tracks |
+| `/tracks/:id` | Get track by ID |
+| `/tracks/:id/stream` | Get stream URLs for a track |
+| `/users/:id` | Get user by ID |
+| `/users/:id/tracks` | Get user's tracks |
+
+## Provider
+
+```tsx
+<SoundCloudProvider apiPrefix="/api/soundcloud">
+  {children}
+</SoundCloudProvider>
+```
+
+The `apiPrefix` prop configures where the hooks send requests. Default: `"/api/soundcloud"`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,179 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }"use client";
+
+// src/client/provider.tsx
+var _react = require('react');
+var _jsxruntime = require('react/jsx-runtime');
+var SoundCloudContext = _react.createContext.call(void 0, {
+  apiPrefix: "/api/soundcloud"
+});
+function SoundCloudProvider({
+  apiPrefix = "/api/soundcloud",
+  children
+}) {
+  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, SoundCloudContext.Provider, { value: { apiPrefix }, children });
+}
+function useSoundCloudContext() {
+  return _react.useContext.call(void 0, SoundCloudContext);
+}
+
+// src/client/hooks/useTrackSearch.ts
+
+function useTrackSearch(query, options) {
+  const { apiPrefix } = useSoundCloudContext();
+  const [data, setData] = _react.useState.call(void 0, null);
+  const [loading, setLoading] = _react.useState.call(void 0, false);
+  const [error, setError] = _react.useState.call(void 0, null);
+  _react.useEffect.call(void 0, () => {
+    if (!query) {
+      setData(null);
+      return;
+    }
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    const params = new URLSearchParams({ q: query });
+    if (_optionalChain([options, 'optionalAccess', _ => _.limit])) params.set("limit", String(options.limit));
+    fetch(`${apiPrefix}/search/tracks?${params}`, {
+      signal: controller.signal
+    }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then((json) => setData(_nullishCoalesce(json.collection, () => ( json)))).catch((err) => {
+      if (err.name !== "AbortError") setError(err);
+    }).finally(() => setLoading(false));
+    return () => controller.abort();
+  }, [query, _optionalChain([options, 'optionalAccess', _2 => _2.limit]), apiPrefix]);
+  return { data, loading, error };
+}
+
+// src/client/hooks/useTrack.ts
+
+function useTrack(trackId) {
+  const { apiPrefix } = useSoundCloudContext();
+  const [data, setData] = _react.useState.call(void 0, null);
+  const [loading, setLoading] = _react.useState.call(void 0, false);
+  const [error, setError] = _react.useState.call(void 0, null);
+  _react.useEffect.call(void 0, () => {
+    if (trackId == null) {
+      setData(null);
+      return;
+    }
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    fetch(`${apiPrefix}/tracks/${trackId}`, { signal: controller.signal }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then(setData).catch((err) => {
+      if (err.name !== "AbortError") setError(err);
+    }).finally(() => setLoading(false));
+    return () => controller.abort();
+  }, [trackId, apiPrefix]);
+  return { data, loading, error };
+}
+
+// src/client/hooks/useUser.ts
+
+function useUser(userId) {
+  const { apiPrefix } = useSoundCloudContext();
+  const [data, setData] = _react.useState.call(void 0, null);
+  const [loading, setLoading] = _react.useState.call(void 0, false);
+  const [error, setError] = _react.useState.call(void 0, null);
+  _react.useEffect.call(void 0, () => {
+    if (userId == null) {
+      setData(null);
+      return;
+    }
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    fetch(`${apiPrefix}/users/${userId}`, { signal: controller.signal }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then(setData).catch((err) => {
+      if (err.name !== "AbortError") setError(err);
+    }).finally(() => setLoading(false));
+    return () => controller.abort();
+  }, [userId, apiPrefix]);
+  return { data, loading, error };
+}
+
+// src/client/hooks/usePlayer.ts
+
+function usePlayer(trackId) {
+  const { apiPrefix } = useSoundCloudContext();
+  const audioRef = _react.useRef.call(void 0, null);
+  const [playing, setPlaying] = _react.useState.call(void 0, false);
+  const [progress, setProgress] = _react.useState.call(void 0, 0);
+  const [duration, setDuration] = _react.useState.call(void 0, 0);
+  _react.useEffect.call(void 0, () => {
+    if (trackId == null) return;
+    const controller = new AbortController();
+    let audio = null;
+    fetch(`${apiPrefix}/tracks/${trackId}/stream`, {
+      signal: controller.signal
+    }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then((json) => {
+      const url = json.url || json.http_mp3_128_url;
+      if (!url) throw new Error("No stream URL returned");
+      audio = new Audio(url);
+      audioRef.current = audio;
+      audio.addEventListener("loadedmetadata", () => {
+        setDuration(audio.duration);
+      });
+      audio.addEventListener("timeupdate", () => {
+        setProgress(audio.currentTime);
+      });
+      audio.addEventListener("ended", () => {
+        setPlaying(false);
+        setProgress(0);
+      });
+    }).catch(() => {
+    });
+    return () => {
+      controller.abort();
+      if (audioRef.current) {
+        audioRef.current.pause();
+        audioRef.current.src = "";
+        audioRef.current = null;
+      }
+      setPlaying(false);
+      setProgress(0);
+      setDuration(0);
+    };
+  }, [trackId, apiPrefix]);
+  const play = _react.useCallback.call(void 0, () => {
+    _optionalChain([audioRef, 'access', _3 => _3.current, 'optionalAccess', _4 => _4.play, 'call', _5 => _5()]);
+    setPlaying(true);
+  }, []);
+  const pause = _react.useCallback.call(void 0, () => {
+    _optionalChain([audioRef, 'access', _6 => _6.current, 'optionalAccess', _7 => _7.pause, 'call', _8 => _8()]);
+    setPlaying(false);
+  }, []);
+  const toggle = _react.useCallback.call(void 0, () => {
+    if (_optionalChain([audioRef, 'access', _9 => _9.current, 'optionalAccess', _10 => _10.paused])) {
+      audioRef.current.play();
+      setPlaying(true);
+    } else {
+      _optionalChain([audioRef, 'access', _11 => _11.current, 'optionalAccess', _12 => _12.pause, 'call', _13 => _13()]);
+      setPlaying(false);
+    }
+  }, []);
+  const seek = _react.useCallback.call(void 0, (time) => {
+    if (audioRef.current) {
+      audioRef.current.currentTime = time;
+      setProgress(time);
+    }
+  }, []);
+  return { playing, progress, duration, play, pause, toggle, seek };
+}
+
+
+
+
+
+
+
+exports.SoundCloudProvider = SoundCloudProvider; exports.usePlayer = usePlayer; exports.useSoundCloudContext = useSoundCloudContext; exports.useTrack = useTrack; exports.useTrackSearch = useTrackSearch; exports.useUser = useUser;

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SoundCloudTrack, SoundCloudUser } from 'soundcloud-api-ts';
+export { SoundCloudActivitiesResponse, SoundCloudActivity, SoundCloudComment, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile } from 'soundcloud-api-ts';
+
+interface SoundCloudContextValue {
+    apiPrefix: string;
+}
+interface SoundCloudProviderProps {
+    /** API route prefix (default: "/api/soundcloud") */
+    apiPrefix?: string;
+    children: ReactNode;
+}
+declare function SoundCloudProvider({ apiPrefix, children, }: SoundCloudProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSoundCloudContext(): SoundCloudContextValue;
+
+/** Configuration for server-side route handlers. */
+interface SoundCloudRoutesConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+}
+/** Standard hook return shape. */
+interface HookResult<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+}
+/** Player hook return shape. */
+interface PlayerState {
+    playing: boolean;
+    progress: number;
+    duration: number;
+    play: () => void;
+    pause: () => void;
+    toggle: () => void;
+    seek: (time: number) => void;
+}
+
+interface UseTrackSearchOptions {
+    limit?: number;
+}
+declare function useTrackSearch(query: string, options?: UseTrackSearchOptions): HookResult<SoundCloudTrack[]>;
+
+declare function useTrack(trackId: string | number | undefined): HookResult<SoundCloudTrack>;
+
+declare function useUser(userId: string | number | undefined): HookResult<SoundCloudUser>;
+
+declare function usePlayer(trackId: string | number | undefined): PlayerState;
+
+export { type HookResult, type PlayerState, SoundCloudProvider, type SoundCloudProviderProps, type SoundCloudRoutesConfig, type UseTrackSearchOptions, usePlayer, useSoundCloudContext, useTrack, useTrackSearch, useUser };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SoundCloudTrack, SoundCloudUser } from 'soundcloud-api-ts';
+export { SoundCloudActivitiesResponse, SoundCloudActivity, SoundCloudComment, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile } from 'soundcloud-api-ts';
+
+interface SoundCloudContextValue {
+    apiPrefix: string;
+}
+interface SoundCloudProviderProps {
+    /** API route prefix (default: "/api/soundcloud") */
+    apiPrefix?: string;
+    children: ReactNode;
+}
+declare function SoundCloudProvider({ apiPrefix, children, }: SoundCloudProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSoundCloudContext(): SoundCloudContextValue;
+
+/** Configuration for server-side route handlers. */
+interface SoundCloudRoutesConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+}
+/** Standard hook return shape. */
+interface HookResult<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+}
+/** Player hook return shape. */
+interface PlayerState {
+    playing: boolean;
+    progress: number;
+    duration: number;
+    play: () => void;
+    pause: () => void;
+    toggle: () => void;
+    seek: (time: number) => void;
+}
+
+interface UseTrackSearchOptions {
+    limit?: number;
+}
+declare function useTrackSearch(query: string, options?: UseTrackSearchOptions): HookResult<SoundCloudTrack[]>;
+
+declare function useTrack(trackId: string | number | undefined): HookResult<SoundCloudTrack>;
+
+declare function useUser(userId: string | number | undefined): HookResult<SoundCloudUser>;
+
+declare function usePlayer(trackId: string | number | undefined): PlayerState;
+
+export { type HookResult, type PlayerState, SoundCloudProvider, type SoundCloudProviderProps, type SoundCloudRoutesConfig, type UseTrackSearchOptions, usePlayer, useSoundCloudContext, useTrack, useTrackSearch, useUser };

package/dist/index.mjs

@@ -0,0 +1,179 @@
+"use client";
+
+// src/client/provider.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var SoundCloudContext = createContext({
+  apiPrefix: "/api/soundcloud"
+});
+function SoundCloudProvider({
+  apiPrefix = "/api/soundcloud",
+  children
+}) {
+  return /* @__PURE__ */ jsx(SoundCloudContext.Provider, { value: { apiPrefix }, children });
+}
+function useSoundCloudContext() {
+  return useContext(SoundCloudContext);
+}
+
+// src/client/hooks/useTrackSearch.ts
+import { useState, useEffect } from "react";
+function useTrackSearch(query, options) {
+  const { apiPrefix } = useSoundCloudContext();
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (!query) {
+      setData(null);
+      return;
+    }
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    const params = new URLSearchParams({ q: query });
+    if (options?.limit) params.set("limit", String(options.limit));
+    fetch(`${apiPrefix}/search/tracks?${params}`, {
+      signal: controller.signal
+    }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then((json) => setData(json.collection ?? json)).catch((err) => {
+      if (err.name !== "AbortError") setError(err);
+    }).finally(() => setLoading(false));
+    return () => controller.abort();
+  }, [query, options?.limit, apiPrefix]);
+  return { data, loading, error };
+}
+
+// src/client/hooks/useTrack.ts
+import { useState as useState2, useEffect as useEffect2 } from "react";
+function useTrack(trackId) {
+  const { apiPrefix } = useSoundCloudContext();
+  const [data, setData] = useState2(null);
+  const [loading, setLoading] = useState2(false);
+  const [error, setError] = useState2(null);
+  useEffect2(() => {
+    if (trackId == null) {
+      setData(null);
+      return;
+    }
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    fetch(`${apiPrefix}/tracks/${trackId}`, { signal: controller.signal }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then(setData).catch((err) => {
+      if (err.name !== "AbortError") setError(err);
+    }).finally(() => setLoading(false));
+    return () => controller.abort();
+  }, [trackId, apiPrefix]);
+  return { data, loading, error };
+}
+
+// src/client/hooks/useUser.ts
+import { useState as useState3, useEffect as useEffect3 } from "react";
+function useUser(userId) {
+  const { apiPrefix } = useSoundCloudContext();
+  const [data, setData] = useState3(null);
+  const [loading, setLoading] = useState3(false);
+  const [error, setError] = useState3(null);
+  useEffect3(() => {
+    if (userId == null) {
+      setData(null);
+      return;
+    }
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    fetch(`${apiPrefix}/users/${userId}`, { signal: controller.signal }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then(setData).catch((err) => {
+      if (err.name !== "AbortError") setError(err);
+    }).finally(() => setLoading(false));
+    return () => controller.abort();
+  }, [userId, apiPrefix]);
+  return { data, loading, error };
+}
+
+// src/client/hooks/usePlayer.ts
+import { useState as useState4, useEffect as useEffect4, useRef, useCallback } from "react";
+function usePlayer(trackId) {
+  const { apiPrefix } = useSoundCloudContext();
+  const audioRef = useRef(null);
+  const [playing, setPlaying] = useState4(false);
+  const [progress, setProgress] = useState4(0);
+  const [duration, setDuration] = useState4(0);
+  useEffect4(() => {
+    if (trackId == null) return;
+    const controller = new AbortController();
+    let audio = null;
+    fetch(`${apiPrefix}/tracks/${trackId}/stream`, {
+      signal: controller.signal
+    }).then((res) => {
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    }).then((json) => {
+      const url = json.url || json.http_mp3_128_url;
+      if (!url) throw new Error("No stream URL returned");
+      audio = new Audio(url);
+      audioRef.current = audio;
+      audio.addEventListener("loadedmetadata", () => {
+        setDuration(audio.duration);
+      });
+      audio.addEventListener("timeupdate", () => {
+        setProgress(audio.currentTime);
+      });
+      audio.addEventListener("ended", () => {
+        setPlaying(false);
+        setProgress(0);
+      });
+    }).catch(() => {
+    });
+    return () => {
+      controller.abort();
+      if (audioRef.current) {
+        audioRef.current.pause();
+        audioRef.current.src = "";
+        audioRef.current = null;
+      }
+      setPlaying(false);
+      setProgress(0);
+      setDuration(0);
+    };
+  }, [trackId, apiPrefix]);
+  const play = useCallback(() => {
+    audioRef.current?.play();
+    setPlaying(true);
+  }, []);
+  const pause = useCallback(() => {
+    audioRef.current?.pause();
+    setPlaying(false);
+  }, []);
+  const toggle = useCallback(() => {
+    if (audioRef.current?.paused) {
+      audioRef.current.play();
+      setPlaying(true);
+    } else {
+      audioRef.current?.pause();
+      setPlaying(false);
+    }
+  }, []);
+  const seek = useCallback((time) => {
+    if (audioRef.current) {
+      audioRef.current.currentTime = time;
+      setProgress(time);
+    }
+  }, []);
+  return { playing, progress, duration, play, pause, toggle, seek };
+}
+export {
+  SoundCloudProvider,
+  usePlayer,
+  useSoundCloudContext,
+  useTrack,
+  useTrackSearch,
+  useUser
+};

package/dist/server.cjs

@@ -0,0 +1,134 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/server/routes.ts
+
+
+
+
+
+
+
+var _soundcloudapits = require('soundcloud-api-ts');
+var ctx = {
+  config: { clientId: "", clientSecret: "" },
+  token: void 0,
+  tokenExpiry: 0
+};
+async function ensureToken() {
+  if (ctx.token && Date.now() < ctx.tokenExpiry) return ctx.token;
+  const result = await _soundcloudapits.getClientToken.call(void 0, ctx.config.clientId, ctx.config.clientSecret);
+  ctx.token = result.access_token;
+  ctx.tokenExpiry = Date.now() + (result.expires_in - 300) * 1e3;
+  return ctx.token;
+}
+function jsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function errorResponse(message, status) {
+  return jsonResponse({ error: message }, status);
+}
+async function handleRoute(pathname, url) {
+  const token = await ensureToken();
+  if (pathname === "/search/tracks") {
+    const q = url.searchParams.get("q");
+    if (!q) return errorResponse("Missing query parameter 'q'", 400);
+    const page = url.searchParams.get("page");
+    const result = await _soundcloudapits.searchTracks.call(void 0, token, q, page ? parseInt(page, 10) : void 0);
+    return jsonResponse(result);
+  }
+  const streamMatch = pathname.match(/^\/tracks\/([^/]+)\/stream$/);
+  if (streamMatch) {
+    const streams = await _soundcloudapits.getTrackStreams.call(void 0, token, streamMatch[1]);
+    return jsonResponse(streams);
+  }
+  const trackMatch = pathname.match(/^\/tracks\/([^/]+)$/);
+  if (trackMatch) {
+    const track = await _soundcloudapits.getTrack.call(void 0, token, trackMatch[1]);
+    return jsonResponse(track);
+  }
+  const userTracksMatch = pathname.match(/^\/users\/([^/]+)\/tracks$/);
+  if (userTracksMatch) {
+    const limit = url.searchParams.get("limit");
+    const result = await _soundcloudapits.getUserTracks.call(void 0, 
+      token,
+      userTracksMatch[1],
+      limit ? parseInt(limit, 10) : void 0
+    );
+    return jsonResponse(result);
+  }
+  const userMatch = pathname.match(/^\/users\/([^/]+)$/);
+  if (userMatch) {
+    const user = await _soundcloudapits.getUser.call(void 0, token, userMatch[1]);
+    return jsonResponse(user);
+  }
+  return errorResponse("Not found", 404);
+}
+function createSoundCloudRoutes(config) {
+  ctx.config = config;
+  ctx.token = void 0;
+  ctx.tokenExpiry = 0;
+  return {
+    /** Individual route handlers */
+    async searchTracks(q, page) {
+      const token = await ensureToken();
+      return _soundcloudapits.searchTracks.call(void 0, token, q, page);
+    },
+    async getTrack(trackId) {
+      const token = await ensureToken();
+      return _soundcloudapits.getTrack.call(void 0, token, trackId);
+    },
+    async getUser(userId) {
+      const token = await ensureToken();
+      return _soundcloudapits.getUser.call(void 0, token, userId);
+    },
+    async getUserTracks(userId, limit) {
+      const token = await ensureToken();
+      return _soundcloudapits.getUserTracks.call(void 0, token, userId, limit);
+    },
+    async getTrackStreams(trackId) {
+      const token = await ensureToken();
+      return _soundcloudapits.getTrackStreams.call(void 0, token, trackId);
+    },
+    /**
+     * App Router catch-all handler.
+     * Mount at `app/api/soundcloud/[...route]/route.ts`
+     */
+    handler() {
+      return async (request) => {
+        try {
+          const url = new URL(request.url);
+          const match = url.pathname.match(/\/api\/soundcloud(\/.*)/);
+          const route = match ? match[1] : url.pathname;
+          return await handleRoute(route, url);
+        } catch (err) {
+          const status = _nullishCoalesce(_optionalChain([err, 'optionalAccess', _ => _.statusCode]), () => ( 500));
+          return errorResponse(_nullishCoalesce(_optionalChain([err, 'optionalAccess', _2 => _2.message]), () => ( "Internal server error")), status);
+        }
+      };
+    },
+    /**
+     * Pages Router catch-all handler.
+     * Mount at `pages/api/soundcloud/[...route].ts`
+     */
+    pagesHandler() {
+      return async (req, res) => {
+        try {
+          const route = Array.isArray(req.query.route) ? "/" + req.query.route.join("/") : _nullishCoalesce(_optionalChain([req, 'access', _3 => _3.url, 'optionalAccess', _4 => _4.replace, 'call', _5 => _5(/^\/api\/soundcloud/, "")]), () => ( "/"));
+          const protocol = req.headers["x-forwarded-proto"] || "http";
+          const host = req.headers.host || "localhost";
+          const url = new URL(`${protocol}://${host}${req.url}`);
+          const response = await handleRoute(route, url);
+          const body = await response.json();
+          res.status(response.status).json(body);
+        } catch (err) {
+          const status = _nullishCoalesce(_optionalChain([err, 'optionalAccess', _6 => _6.statusCode]), () => ( 500));
+          res.status(status).json({ error: _nullishCoalesce(_optionalChain([err, 'optionalAccess', _7 => _7.message]), () => ( "Internal server error")) });
+        }
+      };
+    }
+  };
+}
+
+
+exports.createSoundCloudRoutes = createSoundCloudRoutes;

package/dist/server.d.cts

@@ -0,0 +1,30 @@
+import * as soundcloud_api_ts from 'soundcloud-api-ts';
+
+/** Configuration for server-side route handlers. */
+interface SoundCloudRoutesConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+}
+
+declare function createSoundCloudRoutes(config: SoundCloudRoutesConfig): {
+    /** Individual route handlers */
+    searchTracks(q: string, page?: number): Promise<soundcloud_api_ts.SoundCloudPaginatedResponse<soundcloud_api_ts.SoundCloudTrack>>;
+    getTrack(trackId: string | number): Promise<soundcloud_api_ts.SoundCloudTrack>;
+    getUser(userId: string | number): Promise<soundcloud_api_ts.SoundCloudUser>;
+    getUserTracks(userId: string | number, limit?: number): Promise<soundcloud_api_ts.SoundCloudPaginatedResponse<soundcloud_api_ts.SoundCloudTrack>>;
+    getTrackStreams(trackId: string | number): Promise<soundcloud_api_ts.SoundCloudStreams>;
+    /**
+     * App Router catch-all handler.
+     * Mount at `app/api/soundcloud/[...route]/route.ts`
+     */
+    handler(): (request: Request) => Promise<Response>;
+    /**
+     * Pages Router catch-all handler.
+     * Mount at `pages/api/soundcloud/[...route].ts`
+     */
+    pagesHandler(): (req: any, res: any) => Promise<void>;
+};
+
+export { type SoundCloudRoutesConfig, createSoundCloudRoutes };

package/dist/server.d.ts

@@ -0,0 +1,30 @@
+import * as soundcloud_api_ts from 'soundcloud-api-ts';
+
+/** Configuration for server-side route handlers. */
+interface SoundCloudRoutesConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+}
+
+declare function createSoundCloudRoutes(config: SoundCloudRoutesConfig): {
+    /** Individual route handlers */
+    searchTracks(q: string, page?: number): Promise<soundcloud_api_ts.SoundCloudPaginatedResponse<soundcloud_api_ts.SoundCloudTrack>>;
+    getTrack(trackId: string | number): Promise<soundcloud_api_ts.SoundCloudTrack>;
+    getUser(userId: string | number): Promise<soundcloud_api_ts.SoundCloudUser>;
+    getUserTracks(userId: string | number, limit?: number): Promise<soundcloud_api_ts.SoundCloudPaginatedResponse<soundcloud_api_ts.SoundCloudTrack>>;
+    getTrackStreams(trackId: string | number): Promise<soundcloud_api_ts.SoundCloudStreams>;
+    /**
+     * App Router catch-all handler.
+     * Mount at `app/api/soundcloud/[...route]/route.ts`
+     */
+    handler(): (request: Request) => Promise<Response>;
+    /**
+     * Pages Router catch-all handler.
+     * Mount at `pages/api/soundcloud/[...route].ts`
+     */
+    pagesHandler(): (req: any, res: any) => Promise<void>;
+};
+
+export { type SoundCloudRoutesConfig, createSoundCloudRoutes };

package/dist/server.mjs

@@ -0,0 +1,134 @@
+// src/server/routes.ts
+import {
+  getClientToken,
+  searchTracks,
+  getTrack,
+  getUser,
+  getUserTracks,
+  getTrackStreams
+} from "soundcloud-api-ts";
+var ctx = {
+  config: { clientId: "", clientSecret: "" },
+  token: void 0,
+  tokenExpiry: 0
+};
+async function ensureToken() {
+  if (ctx.token && Date.now() < ctx.tokenExpiry) return ctx.token;
+  const result = await getClientToken(ctx.config.clientId, ctx.config.clientSecret);
+  ctx.token = result.access_token;
+  ctx.tokenExpiry = Date.now() + (result.expires_in - 300) * 1e3;
+  return ctx.token;
+}
+function jsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function errorResponse(message, status) {
+  return jsonResponse({ error: message }, status);
+}
+async function handleRoute(pathname, url) {
+  const token = await ensureToken();
+  if (pathname === "/search/tracks") {
+    const q = url.searchParams.get("q");
+    if (!q) return errorResponse("Missing query parameter 'q'", 400);
+    const page = url.searchParams.get("page");
+    const result = await searchTracks(token, q, page ? parseInt(page, 10) : void 0);
+    return jsonResponse(result);
+  }
+  const streamMatch = pathname.match(/^\/tracks\/([^/]+)\/stream$/);
+  if (streamMatch) {
+    const streams = await getTrackStreams(token, streamMatch[1]);
+    return jsonResponse(streams);
+  }
+  const trackMatch = pathname.match(/^\/tracks\/([^/]+)$/);
+  if (trackMatch) {
+    const track = await getTrack(token, trackMatch[1]);
+    return jsonResponse(track);
+  }
+  const userTracksMatch = pathname.match(/^\/users\/([^/]+)\/tracks$/);
+  if (userTracksMatch) {
+    const limit = url.searchParams.get("limit");
+    const result = await getUserTracks(
+      token,
+      userTracksMatch[1],
+      limit ? parseInt(limit, 10) : void 0
+    );
+    return jsonResponse(result);
+  }
+  const userMatch = pathname.match(/^\/users\/([^/]+)$/);
+  if (userMatch) {
+    const user = await getUser(token, userMatch[1]);
+    return jsonResponse(user);
+  }
+  return errorResponse("Not found", 404);
+}
+function createSoundCloudRoutes(config) {
+  ctx.config = config;
+  ctx.token = void 0;
+  ctx.tokenExpiry = 0;
+  return {
+    /** Individual route handlers */
+    async searchTracks(q, page) {
+      const token = await ensureToken();
+      return searchTracks(token, q, page);
+    },
+    async getTrack(trackId) {
+      const token = await ensureToken();
+      return getTrack(token, trackId);
+    },
+    async getUser(userId) {
+      const token = await ensureToken();
+      return getUser(token, userId);
+    },
+    async getUserTracks(userId, limit) {
+      const token = await ensureToken();
+      return getUserTracks(token, userId, limit);
+    },
+    async getTrackStreams(trackId) {
+      const token = await ensureToken();
+      return getTrackStreams(token, trackId);
+    },
+    /**
+     * App Router catch-all handler.
+     * Mount at `app/api/soundcloud/[...route]/route.ts`
+     */
+    handler() {
+      return async (request) => {
+        try {
+          const url = new URL(request.url);
+          const match = url.pathname.match(/\/api\/soundcloud(\/.*)/);
+          const route = match ? match[1] : url.pathname;
+          return await handleRoute(route, url);
+        } catch (err) {
+          const status = err?.statusCode ?? 500;
+          return errorResponse(err?.message ?? "Internal server error", status);
+        }
+      };
+    },
+    /**
+     * Pages Router catch-all handler.
+     * Mount at `pages/api/soundcloud/[...route].ts`
+     */
+    pagesHandler() {
+      return async (req, res) => {
+        try {
+          const route = Array.isArray(req.query.route) ? "/" + req.query.route.join("/") : req.url?.replace(/^\/api\/soundcloud/, "") ?? "/";
+          const protocol = req.headers["x-forwarded-proto"] || "http";
+          const host = req.headers.host || "localhost";
+          const url = new URL(`${protocol}://${host}${req.url}`);
+          const response = await handleRoute(route, url);
+          const body = await response.json();
+          res.status(response.status).json(body);
+        } catch (err) {
+          const status = err?.statusCode ?? 500;
+          res.status(status).json({ error: err?.message ?? "Internal server error" });
+        }
+      };
+    }
+  };
+}
+export {
+  createSoundCloudRoutes
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "soundcloud-api-ts-next",
+  "version": "1.0.0",
+  "description": "Next.js integration for soundcloud-api-ts — React hooks + secure API route handlers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/twin-paws/soundcloud-api-ts-next"
+  },
+  "homepage": "https://github.com/twin-paws/soundcloud-api-ts-next#readme",
+  "keywords": [
+    "soundcloud",
+    "nextjs",
+    "react",
+    "hooks",
+    "soundcloud-api",
+    "typescript",
+    "soundcloud-next"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "soundcloud-api-ts": "^1.9.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "next": "^13.0.0 || ^14.0.0 || ^15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsup": "^8.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "next": "^15.0.0"
+  }
+}