feat(hub): list collections

packages/hub/src/lib/index.ts

@@ -18,6 +18,7 @@ export * from "./list-datasets";
 export * from "./list-files";
 export * from "./list-models";
 export * from "./list-spaces";
+export * from "./list-collections";
 export * from "./model-info";
 export * from "./oauth-handle-redirect";
 export * from "./oauth-login-url";

packages/hub/src/lib/list-collections.spec.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import { listCollections } from "./list-collections";
+import type { ApiCollectionInfo } from "../types/api/api-collection";
+import { TEST_HUB_URL } from "../test/consts";
+
+describe("listCollections", () => {
+	it("should list collections", async () => {
+		const results: ApiCollectionInfo[] = [];
+
+		for await (const entry of listCollections({
+			search: { owner: ["quanghuynt14"] },
+			hubUrl: TEST_HUB_URL,
+		})) {
+			if (entry.slug !== "quanghuynt14/test-collection-6866ff686ca2d2e0a1931507") {
+				continue;
+			}
+
+			if (typeof entry.lastUpdated === "string") {
+				entry.lastUpdated = "2025-07-03T22:18:56.239Z";
+			}
+
+			if (entry.items && Array.isArray(entry.items)) {
+				entry.items.map((item) => {
+					if ("lastModified" in item && typeof item.lastModified === "string") {
+						item.lastModified = "2025-07-01T00:36:29.000Z";
+					}
+					if ("lastUpdated" in item && typeof item.lastUpdated === "string") {
+						item.lastUpdated = "2025-07-01T00:41:27.525Z";
+					}
+				});
+			}
+
+			results.push(entry);
+		}
+
+		const collection = results[0];
+		const items = collection.items;
+		collection.items = [];
+
+		// Check all properties of the collection except items
+		expect(collection).deep.equal({
+			slug: "quanghuynt14/test-collection-6866ff686ca2d2e0a1931507",
+			title: "Test Collection",
+			description: "This collection is only for test",
+			gating: false,
+			lastUpdated: "2025-07-03T22:18:56.239Z",
+			owner: {
+				_id: "6866ff3936a7677f427f99e3",
+				avatarUrl: "/avatars/b51088e22fb7194888551365b1bafada.svg",
+				fullname: "Quang-Huy Tran",
+				name: "quanghuynt14",
+				type: "user",
+				isPro: false,
+				isHf: false,
+				isHfAdmin: false,
+				isMod: false,
+			},
+			items: [],
+			theme: "purple",
+			private: false,
+			upvotes: 0,
+			isUpvotedByUser: false,
+		});
+
+		// Check for item type model
+		expect(items[0]).deep.equal({
+			_id: "686700086ca2d2e0a193150b",
+			position: 0,
+			type: "model",
+			author: "quanghuynt14",
+			authorData: {
+				_id: "6866ff3936a7677f427f99e3",
+				avatarUrl: "/avatars/b51088e22fb7194888551365b1bafada.svg",
+				fullname: "Quang-Huy Tran",
+				name: "quanghuynt14",
+				type: "user",
+				isPro: false,
+				isHf: false,
+				isHfAdmin: false,
+				isMod: false,
+			},
+			downloads: 0,
+			gated: false,
+			id: "quanghuynt14/TestModel",
+			availableInferenceProviders: [],
+			lastModified: "2025-07-01T00:36:29.000Z",
+			likes: 0,
+			private: false,
+			repoType: "model",
+			isLikedByUser: false,
+		});
+
+		// Check for item type dataset
+		expect(items[1]).deep.equal({
+			_id: "686701cd86ea6972ba6c9da5",
+			position: 1,
+			type: "dataset",
+			author: "quanghuynt14",
+			downloads: 0,
+			gated: false,
+			id: "quanghuynt14/TestDataset",
+			lastModified: "2025-07-01T00:36:29.000Z",
+			private: false,
+			repoType: "dataset",
+			likes: 0,
+			isLikedByUser: false,
+		});
+
+		// Check for item type space
+		expect(items[2]).deep.equal({
+			_id: "6867000f6ca2d2e0a193150e",
+			position: 2,
+			type: "space",
+			author: "quanghuynt14",
+			authorData: {
+				_id: "6866ff3936a7677f427f99e3",
+				avatarUrl: "/avatars/b51088e22fb7194888551365b1bafada.svg",
+				fullname: "Quang-Huy Tran",
+				name: "quanghuynt14",
+				type: "user",
+				isPro: false,
+				isHf: false,
+				isHfAdmin: false,
+				isMod: false,
+			},
+			colorFrom: "pink",
+			colorTo: "indigo",
+			createdAt: "2025-07-03T22:10:39.000Z",
+			emoji: "🏆",
+			id: "quanghuynt14/TestSpace",
+			lastModified: "2025-07-01T00:36:29.000Z",
+			likes: 0,
+			pinned: false,
+			private: false,
+			sdk: "docker",
+			repoType: "space",
+			runtime: {
+				stage: "BUILDING",
+				hardware: {
+					current: null,
+					requested: "cpu-basic",
+				},
+				storage: null,
+				gcTimeout: 172800,
+				replicas: {
+					current: 0,
+					requested: 1,
+				},
+			},
+			shortDescription: "This space is only for test",
+			title: "TestSpace",
+			isLikedByUser: false,
+			trendingScore: 0,
+			tags: ["docker", "region:us"],
+		});
+
+		// Check for item type collection
+		expect(items[3]).deep.equal({
+			_id: "68670014f25517a0a7eaf505",
+			position: 3,
+			type: "collection",
+			id: "6866ff686ca2d2e0a1931507",
+			slug: "quanghuynt14/test-collection-6866ff686ca2d2e0a1931507",
+			title: "Test Collection",
+			description: "This collection is only for test",
+			lastUpdated: "2025-07-01T00:41:27.525Z",
+			numberItems: 5,
+			owner: {
+				_id: "6866ff3936a7677f427f99e3",
+				avatarUrl: "/avatars/b51088e22fb7194888551365b1bafada.svg",
+				fullname: "Quang-Huy Tran",
+				name: "quanghuynt14",
+				type: "user",
+				isPro: false,
+				isHf: false,
+				isHfAdmin: false,
+				isMod: false,
+			},
+			theme: "purple",
+			shareUrl: "https://hub-ci.huggingface.co/collections/quanghuynt14/test-collection-6866ff686ca2d2e0a1931507",
+			upvotes: 0,
+			isUpvotedByUser: false,
+		});
+	});
+});

packages/hub/src/lib/list-collections.ts

@@ -0,0 +1,98 @@
+import { HUB_URL } from "../consts";
+import { createApiError } from "../error";
+import type { CredentialsParams } from "../types/public";
+import { checkCredentials } from "../utils/checkCredentials";
+import { parseLinkHeader } from "../utils/parseLinkHeader";
+import type { ApiCollectionInfo } from "../types/api/api-collection";
+
+export async function* listCollections(
+	params?: {
+		search?: {
+			/**
+			 * Filter collections created by specific owners (users or organizations).
+			 */
+			owner?: string[];
+			/**
+			 * Filter collections containing specific items.
+			 * Value must be the item_type and item_id concatenated.
+			 * Example: "models/teknium/OpenHermes-2.5-Mistral-7B", "datasets/rajpurkar/squad" or "papers/2311.12983".
+			 */
+			item?: string[];
+			/**
+			 * Filter based on substrings for titles & descriptions.
+			 */
+			q?: string;
+		};
+		/**
+		 * Sort the returned collections. Supported values are "lastModified", "trending" (default) and "upvotes".
+		 */
+		sort?: "lastModified" | "trending" | "upvotes";
+		/**
+		 *  Set to limit the number of collections returned.
+		 */
+		limit?: number;
+		hubUrl?: string;
+		/**
+		 * Custom fetch function to use instead of the default one, for example to use a proxy or edit headers.
+		 */
+		fetch?: typeof fetch;
+	} & Partial<CredentialsParams>
+): AsyncGenerator<ApiCollectionInfo> {
+	const accessToken = params && checkCredentials(params);
+
+	const searchParams = new URLSearchParams();
+
+	let totalToFetch = params?.limit ?? Infinity;
+	searchParams.append("limit", String(Math.min(totalToFetch, 100)));
+
+	if (params?.sort) {
+		searchParams.append("sort", params.sort);
+	}
+
+	if (params?.search?.owner) {
+		for (const owner of params.search.owner) {
+			searchParams.append("owner", owner);
+		}
+	}
+
+	if (params?.search?.item) {
+		for (const item of params.search.item) {
+			searchParams.append("item", item);
+		}
+	}
+
+	if (params?.search?.q) {
+		searchParams.append("q", params.search.q);
+	}
+
+	let url: string | undefined = `${params?.hubUrl || HUB_URL}/api/collections?${searchParams}`;
+
+	while (url) {
+		const res: Response = await (params?.fetch ?? fetch)(url, {
+			headers: {
+				accept: "application/json",
+				...(accessToken ? { Authorization: `Bearer ${accessToken}` } : undefined),
+			},
+		});
+
+		if (!res.ok) {
+			throw await createApiError(res);
+		}
+
+		const collections: ApiCollectionInfo[] = await res.json();
+
+		for (const collection of collections) {
+			yield collection;
+
+			totalToFetch--;
+
+			if (totalToFetch <= 0) {
+				return;
+			}
+		}
+
+		const linkHeader = res.headers.get("Link");
+
+		url = linkHeader ? parseLinkHeader(linkHeader).next : undefined;
+	}
+}

packages/hub/src/types/api/api-author.ts

@@ -0,0 +1,26 @@
+export type ApiAuthor =
+	| {
+			avatarUrl: string;
+			fullname: string;
+			name: string;
+			isHf: boolean;
+			isHfAdmin: boolean;
+			isMod: boolean;
+			followerCount?: number;
+			type: "org";
+			isEnterprise: boolean;
+			isUserFollowing?: boolean;
+	  }
+	| {
+			avatarUrl: string;
+			fullname: string;
+			name: string;
+			isHf: boolean;
+			isHfAdmin: boolean;
+			isMod: boolean;
+			followerCount?: number;
+			type: "user";
+			isPro: boolean;
+			_id: string;
+			isUserFollowing?: boolean;
+	  };