feat(hub): add and delete collection item (#1606)

Issue: #271

**Add a item to a collection:**
- API doc:
https://huggingface.co/docs/hub/api#post-apicollectionsnamespaceslug-iditem
- Python client:
https://github.com/huggingface/huggingface_hub/blob/83bcc0bc40619bd68bfd6af51329f7afd9eed998/src/huggingface_hub/hf_api.py#L8523

**Delete a item from a collection:**
- API doc:
https://huggingface.co/docs/hub/api#delete-apicollectionsnamespaceslug-iditemsitemid
- Python client:
https://github.com/huggingface/huggingface_hub/blob/83bcc0bc40619bd68bfd6af51329f7afd9eed998/src/huggingface_hub/hf_api.py#L8658

Author: quanghuynt14

packages/hub/src/lib/add-collection-item.spec.ts

@@ -0,0 +1,55 @@
+import { it, describe, expect } from "vitest";
+
+import { TEST_HUB_URL, TEST_ACCESS_TOKEN, TEST_USER } from "../test/consts";
+import { addCollectionItem } from "./add-collection-item";
+import { listCollections } from "./list-collections";
+import { collectionInfo } from "./collection-info";
+import { deleteCollectionItem } from "./delete-collection-item";
+
+describe("addCollectionItem", () => {
+	it("should add a item to a collection", async () => {
+		let slug: string = "";
+		let itemId: string = "";
+
+		try {
+			for await (const entry of listCollections({
+				search: { owner: [TEST_USER] },
+				limit: 1,
+				hubUrl: TEST_HUB_URL,
+			})) {
+				slug = entry.slug;
+				break;
+			}
+
+			await addCollectionItem({
+				slug,
+				item: {
+					type: "model",
+					id: "quanghuynt14/TestAddCollectionItem",
+				},
+				note: "This is a test item",
+				accessToken: TEST_ACCESS_TOKEN,
+				hubUrl: TEST_HUB_URL,
+			});
+
+			const collection = await collectionInfo({
+				slug,
+				accessToken: TEST_ACCESS_TOKEN,
+				hubUrl: TEST_HUB_URL,
+			});
+
+			const item = collection.items.find((item) => item.id === "quanghuynt14/TestAddCollectionItem");
+
+			expect(item).toBeDefined();
+
+			itemId = item?._id || "";
+		} finally {
+			await deleteCollectionItem({
+				slug,
+				itemId,
+				accessToken: TEST_ACCESS_TOKEN,
+				hubUrl: TEST_HUB_URL,
+			});
+		}
+	});
+});

packages/hub/src/lib/add-collection-item.ts

@@ -0,0 +1,47 @@
+import { HUB_URL } from "../consts";
+import { createApiError } from "../error";
+import type { CredentialsParams } from "../types/public";
+import { checkCredentials } from "../utils/checkCredentials";
+
+export async function addCollectionItem(
+	params: {
+		/**
+		 * The slug of the collection to add the item to.
+		 */
+		slug: string;
+		/**
+		 * The item to add to the collection.
+		 */
+		item: {
+			type: "paper" | "collection" | "space" | "model" | "dataset";
+			id: string;
+		};
+		/**
+		 * A note to attach to the item in the collection. The maximum size for a note is 500 characters.
+		 */
+		note?: string;
+		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>
+): Promise<void> {
+	const accessToken = checkCredentials(params);
+
+	const res = await (params.fetch ?? fetch)(`${params.hubUrl ?? HUB_URL}/api/collections/${params.slug}/items`, {
+		method: "POST",
+		body: JSON.stringify({
+			item: params.item,
+			note: params.note,
+		}),
+		headers: {
+			Authorization: `Bearer ${accessToken}`,
+			"Content-Type": "application/json",
+		},
+	});
+
+	if (!res.ok) {
+		throw await createApiError(res);
+	}
+}

packages/hub/src/lib/create-collection.spec.ts

@@ -1,32 +1,26 @@
 import { it, describe, expect } from "vitest";
 
-import { TEST_HUB_URL, TEST_ACCESS_TOKEN } from "../test/consts";
+import { TEST_HUB_URL, TEST_ACCESS_TOKEN, TEST_USER } from "../test/consts";
 import { createCollection } from "./create-collection";
-import { whoAmI } from "./who-am-i";
 import { deleteCollection } from "./delete-collection";
 
 describe("createCollection", () => {
 	it("should create a collection", async () => {
 		let slug: string = "";
 
 		try {
-			const user = await whoAmI({
-				hubUrl: TEST_HUB_URL,
-				accessToken: TEST_ACCESS_TOKEN,
-			});
-
 			const result = await createCollection({
 				collection: {
 					title: "Test Collection",
-					namespace: user.name,
+					namespace: TEST_USER,
 					description: "This is a test collection",
 					private: false,
 				},
 				accessToken: TEST_ACCESS_TOKEN,
 				hubUrl: TEST_HUB_URL,
 			});
 
-			expect(result.slug.startsWith(`${user.name}/test-collection`)).toBe(true);
+			expect(result.slug.startsWith(`${TEST_USER}/test-collection`)).toBe(true);
 
 			slug = result.slug;
 		} finally {

packages/hub/src/lib/delete-collection-item.ts

@@ -0,0 +1,40 @@
+import { HUB_URL } from "../consts";
+import { createApiError } from "../error";
+import type { CredentialsParams } from "../types/public";
+import { checkCredentials } from "../utils/checkCredentials";
+
+export async function deleteCollectionItem(
+	params: {
+		/**
+		 * The slug of the collection to delete the item from.
+		 */
+		slug: string;
+		/**
+		 * The item object id which is different from the repo_id/paper_id provided when adding the item to the collection.
+		 * This should be the _id property of the item.
+		 */
+		itemId: string;
+		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>
+): Promise<void> {
+	const accessToken = checkCredentials(params);
+
+	const res = await (params.fetch ?? fetch)(
+		`${params.hubUrl ?? HUB_URL}/api/collections/${params.slug}/items/${params.itemId}`,
+		{
+			method: "DELETE",
+			headers: {
+				Authorization: `Bearer ${accessToken}`,
+				"Content-Type": "application/json",
+			},
+		}
+	);
+
+	if (!res.ok) {
+		throw await createApiError(res);
+	}
+}