@pyqdeck/community-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raiyan Hasan
+
+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

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @pyqdeck/community-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed client for the PYQDeck Community API. It works in React Native (Expo, Hermes) and the browser. It has **no cache,
+no Clerk and no React inside**: your app passes a `getToken()` function and owns caching, retries and optimistic updates
+(for example with TanStack Query).
+
+```ts
+import { createCommunityClient, communityKeys } from "@pyqdeck/community-sdk";
+
+const community = createCommunityClient({
+  baseUrl: "https://community-api.pyqdeck.in",
+  community: "beu", // one client per community
+  getToken: async () => (await clerk.session?.getToken()) ?? null,
+});
+
+// Read
+const feed = await community.posts.feed({ hashtag: "dsa", limit: 20 }); // { items, nextCursor, hasMore }
+const next = await community.posts.feed({ cursor: feed.nextCursor! });
+
+// Publish with images in one call (upload, check, create), with progress and cancel
+const post = await community.publishPost({
+  body: "Dijkstra notes #dsa",
+  images: [{ uri, mimeType: "image/jpeg", size }],
+  onProgress: (p) => setProgress(p), // 0..1
+  signal: controller.signal,
+});
+
+// React with TanStack Query: keys always start with the community
+useQuery({
+  queryKey: communityKeys.feed("beu", { hashtag: "dsa" }),
+  queryFn: ({ signal }) => community.posts.feed({ hashtag: "dsa" }, { signal }),
+});
+```
+
+## Errors
+
+Every failure is a `CommunityApiError` with `status` (0 means no answer from the server), a stable `code`
+(`not_found`, `unauthorized`, `too_many_requests`, `unprocessable_entity`, `network_error`, `timeout`, `aborted`),
+`retryAfterMs` for rate limits, and `requestId` to quote in bug reports. `message` is safe to show to students.
+
+## Good to know
+
+- Every method takes `{ signal }` as its last argument.
+- Responses contain only JSON-safe values (dates are ISO strings), so they can be persisted.
+- Send an idempotency key (`publishPost` does this for you) so a retry after a timeout never creates a duplicate.
+- The API surface lives at `/api/v1`. A breaking API change means a new major version of this package.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,181 @@
+import { type HttpOptions, type RequestOptions } from "./http.js";
+import type { Comment, CommunityInfo, LinkInfo, LinkedResource, LocalImage, Member, MediaItem, Notification, NotificationType, OwnMember, Page, PageParams, Post, ProfileUpdate, ReportGroup, ReportReason, ReportTarget, TrendingTag, UploadTicket } from "./types.js";
+import { type FileUploader } from "./upload.js";
+export interface CommunityClientOptions extends HttpOptions {
+    /** The community this client talks to (`beu`, `gate`, ...). Added to every path; one client per app (IR-SDK-12). */
+    community: string;
+    /** Override how bytes reach the storage provider (defaults to XMLHttpRequest with progress). */
+    uploadFile?: FileUploader;
+}
+export interface CreatePostInput {
+    body?: string;
+    mediaIds?: string[];
+    linkedResource?: LinkedResource;
+}
+export interface EditPostInput {
+    body?: string;
+    mediaIds?: string[];
+    linkedResource?: LinkedResource | null;
+}
+export interface PublishPostInput {
+    body?: string;
+    images?: LocalImage[];
+    linkedResource?: LinkedResource;
+    /** 0 to 1: image bytes first, then the final publish step. */
+    onProgress?: (progress: number) => void;
+    signal?: AbortSignal;
+    /** Reuse the same key when retrying so a lost response cannot create a second post. */
+    idempotencyKey?: string;
+}
+export interface FeedParams extends PageParams {
+    hashtag?: string;
+    /** Search text (2-100 characters). */
+    q?: string;
+}
+/** A new random key for `Idempotency-Key`. */
+export declare const newIdempotencyKey: () => string;
+export declare function createCommunityClient(options: CommunityClientOptions): {
+    community: string;
+    info: (o?: RequestOptions) => Promise<CommunityInfo>;
+    posts: {
+        feed: (p?: FeedParams, o?: RequestOptions) => Promise<Page<Post>>;
+        get: (idOrSlug: string, o?: RequestOptions) => Promise<Post>;
+        create: (input: CreatePostInput, o?: RequestOptions & {
+            idempotencyKey?: string;
+        }) => Promise<Post>;
+        edit: (id: string, input: EditPostInput, o?: RequestOptions) => Promise<Post>;
+        delete: (id: string, o?: RequestOptions) => Promise<undefined>;
+        like: (id: string, o?: RequestOptions) => Promise<{
+            likesCount: number;
+            isLiked: boolean;
+        }>;
+        unlike: (id: string, o?: RequestOptions) => Promise<{
+            likesCount: number;
+            isLiked: boolean;
+        }>;
+        bookmark: (id: string, o?: RequestOptions) => Promise<{
+            bookmarksCount: number;
+            isBookmarked: boolean;
+        }>;
+        unbookmark: (id: string, o?: RequestOptions) => Promise<{
+            bookmarksCount: number;
+            isBookmarked: boolean;
+        }>;
+        hide: (id: string, o?: RequestOptions) => Promise<undefined>;
+        unhide: (id: string, o?: RequestOptions) => Promise<undefined>;
+        bookmarks: (p?: PageParams, o?: RequestOptions) => Promise<Page<Post>>;
+        byMember: (username: string, p?: PageParams, o?: RequestOptions) => Promise<Page<Post>>;
+        trending: (o?: RequestOptions) => Promise<TrendingTag[]>;
+        moderate: (id: string, action: "approve" | "remove" | "reject_edit", reason?: ReportReason, o?: RequestOptions) => Promise<Post>;
+        queue: (p?: PageParams, o?: RequestOptions) => Promise<Page<Post>>;
+    };
+    comments: {
+        list: (postId: string, p?: PageParams, o?: RequestOptions) => Promise<Page<Comment>>;
+        replies: (commentId: string, p?: PageParams, o?: RequestOptions) => Promise<Page<Comment>>;
+        /** `parentId` is any comment of the thread; the server attaches the reply to the thread's top-level comment. */
+        create: (postId: string, input: {
+            body: string;
+            parentId?: string;
+        }, o?: RequestOptions & {
+            idempotencyKey?: string;
+        }) => Promise<Comment>;
+        edit: (id: string, body: string, o?: RequestOptions) => Promise<Comment>;
+        delete: (id: string, o?: RequestOptions) => Promise<undefined>;
+        like: (id: string, o?: RequestOptions) => Promise<{
+            likesCount: number;
+            isLiked: boolean;
+        }>;
+        unlike: (id: string, o?: RequestOptions) => Promise<{
+            likesCount: number;
+            isLiked: boolean;
+        }>;
+        moderate: (id: string, action: "approve" | "remove" | "reject_edit", reason?: ReportReason, o?: RequestOptions) => Promise<Comment>;
+        queue: (p?: PageParams, o?: RequestOptions) => Promise<Page<Comment>>;
+    };
+    members: {
+        me: (o?: RequestOptions) => Promise<OwnMember>;
+        updateMe: (patch: ProfileUpdate, o?: RequestOptions) => Promise<OwnMember>;
+        get: (username: string, o?: RequestOptions) => Promise<Member>;
+        search: (q: string, limit?: number, o?: RequestOptions) => Promise<Member[]>;
+        followers: (username: string, p?: PageParams, o?: RequestOptions) => Promise<Page<Member>>;
+        following: (username: string, p?: PageParams, o?: RequestOptions) => Promise<Page<Member>>;
+        follow: (username: string, o?: RequestOptions) => Promise<{
+            isFollowing: boolean;
+            followersCount: number;
+        }>;
+        unfollow: (username: string, o?: RequestOptions) => Promise<{
+            isFollowing: boolean;
+            followersCount: number;
+        }>;
+        block: (username: string, o?: RequestOptions) => Promise<undefined>;
+        unblock: (username: string, o?: RequestOptions) => Promise<undefined>;
+        blocked: (p?: PageParams, o?: RequestOptions) => Promise<Page<Member>>;
+        suspend: (username: string, reason: string, until?: string, o?: RequestOptions) => Promise<undefined>;
+        unsuspend: (username: string, o?: RequestOptions) => Promise<undefined>;
+        setRole: (username: string, role: "member" | "moderator" | "admin", o?: RequestOptions) => Promise<{
+            username: string;
+            role: string;
+        }>;
+    };
+    notifications: {
+        list: (p?: PageParams & {
+            unread?: boolean;
+            type?: NotificationType;
+        }, o?: RequestOptions) => Promise<Page<Notification>>;
+        unreadCount: (o?: RequestOptions) => Promise<number>;
+        markRead: (id: string, o?: RequestOptions) => Promise<undefined>;
+        markAllRead: (o?: RequestOptions) => Promise<undefined>;
+        dismiss: (id: string, o?: RequestOptions) => Promise<undefined>;
+    };
+    reports: {
+        create: (input: {
+            targetType: ReportTarget;
+            targetId: string;
+            reason: ReportReason;
+            note?: string;
+        }, o?: RequestOptions) => Promise<{
+            received: boolean;
+            duplicate: boolean;
+        }>;
+        queue: (p?: {
+            page?: number;
+            limit?: number;
+        }, o?: RequestOptions) => Promise<ReportGroup[]>;
+        resolve: (input: {
+            targetType: ReportTarget;
+            targetId: string;
+            outcome: "actioned" | "dismissed";
+            remove?: boolean;
+        }, o?: RequestOptions) => Promise<{
+            closed: number;
+        }>;
+    };
+    links: {
+        /** Destination host and safety verdict, so the app can show its own warning before opening a link. */
+        resolve: (code: string, o?: RequestOptions) => Promise<LinkInfo>;
+        block: (code: string, o?: RequestOptions) => Promise<undefined>;
+        unblock: (code: string, o?: RequestOptions) => Promise<undefined>;
+    };
+    media: {
+        requestUploads: (files: Array<{
+            mimeType: string;
+            size: number;
+        }>, o?: RequestOptions) => Promise<{
+            id: string;
+            upload: UploadTicket;
+        }[]>;
+        complete: (id: string, o?: RequestOptions) => Promise<MediaItem>;
+        remove: (id: string, o?: RequestOptions) => Promise<undefined>;
+        /**
+         * The whole direct-upload sequence as one call: ask for tickets, send each image straight to the storage provider,
+         * then have the server confirm and check each one. Returns media ids ready to attach (IR-SDK-4). Uploads that were
+         * started are removed again if anything fails or the call is cancelled.
+         */
+        uploadImages: (images: LocalImage[], opts?: {
+            onProgress?: (fraction: number) => void;
+            signal?: AbortSignal;
+        }) => Promise<MediaItem[]>;
+    };
+    publishPost: (input: PublishPostInput) => Promise<Post>;
+};
+export type CommunityClient = ReturnType<typeof createCommunityClient>;

package/dist/client.js

@@ -0,0 +1,175 @@
+import { CommunityApiError } from "./errors.js";
+import { Http } from "./http.js";
+import { xhrUploader } from "./upload.js";
+const toPage = (env) => ({
+    items: env.data,
+    nextCursor: env.pagination?.nextCursor ?? null,
+    hasMore: env.pagination?.hasMore ?? false,
+});
+/** A new random key for `Idempotency-Key`. */
+export const newIdempotencyKey = () => `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+export function createCommunityClient(options) {
+    const http = new Http(options);
+    const uploadFile = options.uploadFile ?? xhrUploader;
+    const root = `/api/v1/communities/${encodeURIComponent(options.community)}`;
+    const enc = encodeURIComponent;
+    const get = (path, query, o) => http.call({ method: "GET", path: root + path, query, ...o });
+    const send = (method, path, body, o) => http.call({ method, path: root + path, body, ...o });
+    const page = async (path, query, o) => toPage(await get(path, query, o));
+    // ---- posts ----
+    const posts = {
+        feed: (p = {}, o) => page("/posts", { ...p }, o),
+        get: async (idOrSlug, o) => (await get(`/posts/${enc(idOrSlug)}`, undefined, o)).data,
+        create: async (input, o) => (await send("POST", "/posts", input, {
+            ...o,
+            headers: { ...o?.headers, ...(o?.idempotencyKey && { "Idempotency-Key": o.idempotencyKey }) },
+        })).data,
+        edit: async (id, input, o) => (await send("PATCH", `/posts/${enc(id)}`, input, o)).data,
+        delete: async (id, o) => void (await send("DELETE", `/posts/${enc(id)}`, undefined, o)),
+        like: async (id, o) => (await send("PUT", `/posts/${enc(id)}/like`, undefined, o)).data,
+        unlike: async (id, o) => (await send("DELETE", `/posts/${enc(id)}/like`, undefined, o)).data,
+        bookmark: async (id, o) => (await send("PUT", `/posts/${enc(id)}/bookmark`, undefined, o))
+            .data,
+        unbookmark: async (id, o) => (await send("DELETE", `/posts/${enc(id)}/bookmark`, undefined, o)).data,
+        hide: async (id, o) => void (await send("PUT", `/posts/${enc(id)}/hide`, undefined, o)),
+        unhide: async (id, o) => void (await send("DELETE", `/posts/${enc(id)}/hide`, undefined, o)),
+        bookmarks: (p = {}, o) => page("/members/me/bookmarks", { ...p }, o),
+        byMember: (username, p = {}, o) => page(`/members/${enc(username)}/posts`, { ...p }, o),
+        trending: async (o) => (await get("/hashtags/trending", undefined, o)).data,
+        moderate: async (id, action, reason, o) => (await send("POST", `/posts/${enc(id)}/moderate`, { action, reason }, o)).data,
+        queue: (p = {}, o) => page("/posts/queue", { ...p }, o),
+    };
+    // ---- comments ----
+    const comments = {
+        list: (postId, p = {}, o) => page(`/posts/${enc(postId)}/comments`, { ...p }, o),
+        replies: (commentId, p = {}, o) => page(`/comments/${enc(commentId)}/replies`, { ...p }, o),
+        /** `parentId` is any comment of the thread; the server attaches the reply to the thread's top-level comment. */
+        create: async (postId, input, o) => (await send("POST", `/posts/${enc(postId)}/comments`, input, {
+            ...o,
+            headers: { ...o?.headers, ...(o?.idempotencyKey && { "Idempotency-Key": o.idempotencyKey }) },
+        })).data,
+        edit: async (id, body, o) => (await send("PATCH", `/comments/${enc(id)}`, { body }, o)).data,
+        delete: async (id, o) => void (await send("DELETE", `/comments/${enc(id)}`, undefined, o)),
+        like: async (id, o) => (await send("PUT", `/comments/${enc(id)}/like`, undefined, o)).data,
+        unlike: async (id, o) => (await send("DELETE", `/comments/${enc(id)}/like`, undefined, o)).data,
+        moderate: async (id, action, reason, o) => (await send("POST", `/comments/${enc(id)}/moderate`, { action, reason }, o)).data,
+        queue: (p = {}, o) => page("/comments/queue", { ...p }, o),
+    };
+    // ---- members ----
+    const members = {
+        me: async (o) => (await get("/members/me", undefined, o)).data,
+        updateMe: async (patch, o) => (await send("PATCH", "/members/me", patch, o)).data,
+        get: async (username, o) => (await get(`/members/${enc(username)}`, undefined, o)).data,
+        search: async (q, limit, o) => (await get("/members/search", { q, limit }, o)).data,
+        followers: (username, p = {}, o) => page(`/members/${enc(username)}/followers`, { ...p }, o),
+        following: (username, p = {}, o) => page(`/members/${enc(username)}/following`, { ...p }, o),
+        follow: async (username, o) => (await send("PUT", `/members/${enc(username)}/follow`, undefined, o)).data,
+        unfollow: async (username, o) => (await send("DELETE", `/members/${enc(username)}/follow`, undefined, o)).data,
+        block: async (username, o) => void (await send("PUT", `/members/${enc(username)}/block`, undefined, o)),
+        unblock: async (username, o) => void (await send("DELETE", `/members/${enc(username)}/block`, undefined, o)),
+        blocked: (p = {}, o) => page("/members/me/blocked", { ...p }, o),
+        suspend: async (username, reason, until, o) => void (await send("PUT", `/members/${enc(username)}/suspend`, { reason, until }, o)),
+        unsuspend: async (username, o) => void (await send("DELETE", `/members/${enc(username)}/suspend`, undefined, o)),
+        setRole: async (username, role, o) => (await send("PUT", `/members/${enc(username)}/role`, { role }, o)).data,
+    };
+    // ---- notifications ----
+    const notifications = {
+        list: (p = {}, o) => page("/notifications", { ...p }, o),
+        unreadCount: async (o) => (await get("/notifications/unread-count", undefined, o)).data.count,
+        markRead: async (id, o) => void (await send("PATCH", `/notifications/${enc(id)}`, { read: true }, o)),
+        markAllRead: async (o) => void (await send("POST", "/notifications/read-all", undefined, o)),
+        dismiss: async (id, o) => void (await send("DELETE", `/notifications/${enc(id)}`, undefined, o)),
+    };
+    // ---- reports and links ----
+    const reports = {
+        create: async (input, o) => (await send("POST", "/reports", input, o)).data,
+        queue: async (p = {}, o) => (await get("/reports", { ...p }, o)).data,
+        resolve: async (input, o) => (await send("POST", "/reports/resolve", input, o)).data,
+    };
+    const links = {
+        /** Destination host and safety verdict, so the app can show its own warning before opening a link. */
+        resolve: async (code, o) => (await get(`/links/${enc(code)}`, undefined, o)).data,
+        block: async (code, o) => void (await send("POST", `/links/${enc(code)}/block`, undefined, o)),
+        unblock: async (code, o) => void (await send("DELETE", `/links/${enc(code)}/block`, undefined, o)),
+    };
+    // ---- media ----
+    const media = {
+        requestUploads: async (files, o) => (await send("POST", "/media/uploads", { files }, o)).data,
+        complete: async (id, o) => (await send("POST", `/media/${enc(id)}/complete`, undefined, o)).data,
+        remove: async (id, o) => void (await send("DELETE", `/media/${enc(id)}`, undefined, o)),
+        /**
+         * The whole direct-upload sequence as one call: ask for tickets, send each image straight to the storage provider,
+         * then have the server confirm and check each one. Returns media ids ready to attach (IR-SDK-4). Uploads that were
+         * started are removed again if anything fails or the call is cancelled.
+         */
+        uploadImages: async (images, opts = {}) => {
+            if (images.length === 0)
+                return [];
+            const started = [];
+            try {
+                const tickets = await media.requestUploads(images.map((i) => ({ mimeType: i.mimeType, size: i.size })), { signal: opts.signal });
+                started.push(...tickets.map((t) => t.id));
+                const total = images.reduce((sum, i) => sum + i.size, 0) || 1;
+                const sent = new Array(images.length).fill(0);
+                const report = () => opts.onProgress?.(sent.reduce((a, b) => a + b, 0) / total);
+                await Promise.all(tickets.map((t, i) => uploadFile({
+                    ticket: t.upload,
+                    image: images[i],
+                    signal: opts.signal,
+                    onProgress: (loaded, size) => {
+                        sent[i] = Math.min(images[i].size, size ? (loaded / size) * images[i].size : loaded);
+                        report();
+                    },
+                }).then(() => {
+                    sent[i] = images[i].size;
+                    report();
+                })));
+                const done = [];
+                for (const t of tickets)
+                    done.push(await media.complete(t.id, { signal: opts.signal }));
+                return done;
+            }
+            catch (err) {
+                await Promise.allSettled(started.map((id) => media.remove(id)));
+                throw err;
+            }
+        },
+    };
+    /**
+     * Publishes a post with its images in one operation, with progress and cancellation (IR-SDK-3). Images count for
+     * the first 90% of progress; the final create call for the rest. The server answers 422 when moderation refuses
+     * the text, and returns a `pending` post when it is held for review.
+     */
+    const publishPost = async (input) => {
+        const key = input.idempotencyKey ?? newIdempotencyKey();
+        input.onProgress?.(0);
+        const uploaded = await media.uploadImages(input.images ?? [], {
+            signal: input.signal,
+            onProgress: (f) => input.onProgress?.(f * 0.9),
+        });
+        try {
+            const post = await posts.create({ body: input.body, mediaIds: uploaded.map((m) => m.id), linkedResource: input.linkedResource }, { signal: input.signal, idempotencyKey: key });
+            input.onProgress?.(1);
+            return post;
+        }
+        catch (err) {
+            // A refused or cancelled post must not leave its images behind. A network failure keeps them so a retry can reuse them.
+            if (!(err instanceof CommunityApiError) || err.status !== 0) {
+                await Promise.allSettled(uploaded.map((m) => media.remove(m.id)));
+            }
+            throw err;
+        }
+    };
+    return {
+        community: options.community,
+        info: async (o) => (await get("/", undefined, o)).data,
+        posts,
+        comments,
+        members,
+        notifications,
+        reports,
+        links,
+        media,
+        publishPost,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Every failure from the API (or the network) arrives as one of these, so the app can branch on `status` and `code`
+ * without parsing messages. `message` is written for students and safe to show.
+ */
+export declare class CommunityApiError extends Error {
+    /** HTTP status, or 0 when the request never got an answer (offline, timeout, aborted). */
+    readonly status: number;
+    /** Stable code such as `not_found`, `too_many_requests`, `unprocessable_entity`, `network_error`, `aborted`. */
+    readonly code: string;
+    /** From the Retry-After header on 429/503; null otherwise. */
+    readonly retryAfterMs: number | null;
+    readonly requestId: string | null;
+    /** Field errors for validation failures: `{ body: ["Required"] }`. */
+    readonly details: unknown;
+    readonly name = "CommunityApiError";
+    constructor(message: string, 
+    /** HTTP status, or 0 when the request never got an answer (offline, timeout, aborted). */
+    status: number, 
+    /** Stable code such as `not_found`, `too_many_requests`, `unprocessable_entity`, `network_error`, `aborted`. */
+    code: string, 
+    /** From the Retry-After header on 429/503; null otherwise. */
+    retryAfterMs?: number | null, requestId?: string | null, 
+    /** Field errors for validation failures: `{ body: ["Required"] }`. */
+    details?: unknown);
+    get isNetworkError(): boolean;
+    get isUnauthorized(): boolean;
+    get isRateLimited(): boolean;
+    /** Content was refused by moderation or link checks. */
+    get isRefused(): boolean;
+}
+export declare const isAbortError: (err: unknown) => err is CommunityApiError;

package/dist/errors.js

@@ -0,0 +1,37 @@
+/**
+ * Every failure from the API (or the network) arrives as one of these, so the app can branch on `status` and `code`
+ * without parsing messages. `message` is written for students and safe to show.
+ */
+export class CommunityApiError extends Error {
+    constructor(message, 
+    /** HTTP status, or 0 when the request never got an answer (offline, timeout, aborted). */
+    status, 
+    /** Stable code such as `not_found`, `too_many_requests`, `unprocessable_entity`, `network_error`, `aborted`. */
+    code, 
+    /** From the Retry-After header on 429/503; null otherwise. */
+    retryAfterMs = null, requestId = null, 
+    /** Field errors for validation failures: `{ body: ["Required"] }`. */
+    details = undefined) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.requestId = requestId;
+        this.details = details;
+        this.name = "CommunityApiError";
+    }
+    get isNetworkError() {
+        return this.status === 0;
+    }
+    get isUnauthorized() {
+        return this.status === 401;
+    }
+    get isRateLimited() {
+        return this.status === 429;
+    }
+    /** Content was refused by moderation or link checks. */
+    get isRefused() {
+        return this.status === 422;
+    }
+}
+export const isAbortError = (err) => err instanceof CommunityApiError && err.code === "aborted";

package/dist/http.d.ts

@@ -0,0 +1,36 @@
+export interface HttpOptions {
+    /** Origin of the Community API, e.g. https://community-api.pyqdeck.in. Separate from the main API's origin. */
+    baseUrl: string;
+    /** The same Clerk token source the app's main API client uses. Return null when signed out. */
+    getToken: () => Promise<string | null>;
+    fetch?: typeof fetch;
+    /** Per-request timeout. Default 15 s. Implemented with AbortController: Hermes has no AbortSignal.timeout. */
+    timeoutMs?: number;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+interface Call extends RequestOptions {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+}
+export interface Envelope<T> {
+    data: T;
+    pagination?: {
+        nextCursor?: string | null;
+        hasMore?: boolean;
+    };
+}
+export declare class Http {
+    private readonly options;
+    private readonly doFetch;
+    constructor(options: HttpOptions);
+    get baseUrl(): string;
+    getToken(): Promise<string | null>;
+    call<T>(call: Call): Promise<Envelope<T>>;
+    private parse;
+}
+export {};

package/dist/http.js

@@ -0,0 +1,81 @@
+/// <reference lib="dom" />
+import { CommunityApiError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 15000;
+export class Http {
+    constructor(options) {
+        this.options = options;
+        this.doFetch = options.fetch ?? ((...args) => fetch(...args));
+    }
+    get baseUrl() {
+        return this.options.baseUrl.replace(/\/+$/, "");
+    }
+    getToken() {
+        return this.options.getToken();
+    }
+    async call(call) {
+        const url = new URL(this.baseUrl + call.path);
+        for (const [key, value] of Object.entries(call.query ?? {})) {
+            if (value !== undefined && value !== null && value !== "")
+                url.searchParams.set(key, String(value));
+        }
+        // Sends no Authorization header when signed out, so the server answers with its own 401.
+        const token = await this.options.getToken().catch(() => null);
+        const headers = {
+            Accept: "application/json",
+            ...(call.body !== undefined && { "Content-Type": "application/json" }),
+            ...(token && { Authorization: `Bearer ${token}` }),
+            ...call.headers,
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const onOuterAbort = () => controller.abort();
+        if (call.signal) {
+            if (call.signal.aborted)
+                controller.abort();
+            else
+                call.signal.addEventListener("abort", onOuterAbort, { once: true });
+        }
+        if (call.signal?.aborted) {
+            clearTimeout(timer);
+            throw new CommunityApiError("Request cancelled", 0, "aborted");
+        }
+        let response;
+        try {
+            response = await this.doFetch(url.toString(), {
+                method: call.method,
+                headers,
+                body: call.body === undefined ? undefined : JSON.stringify(call.body),
+                signal: controller.signal,
+            });
+        }
+        catch {
+            const timedOut = !call.signal?.aborted && controller.signal.aborted;
+            if (call.signal?.aborted)
+                throw new CommunityApiError("Request cancelled", 0, "aborted");
+            throw new CommunityApiError(timedOut
+                ? "The request took too long. Check your connection and try again."
+                : "Could not reach the server. Check your connection.", 0, timedOut ? "timeout" : "network_error");
+        }
+        finally {
+            clearTimeout(timer);
+            call.signal?.removeEventListener("abort", onOuterAbort);
+        }
+        return this.parse(response);
+    }
+    async parse(response) {
+        if (response.status === 204)
+            return { data: undefined };
+        let json;
+        try {
+            json = await response.json();
+        }
+        catch {
+            json = null;
+        }
+        if (!response.ok || !json || json.success === false) {
+            const retryAfter = Number(response.headers.get("retry-after"));
+            throw new CommunityApiError(json?.message ?? `Something went wrong (${response.status})`, response.status, json?.code ?? `http_${response.status}`, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : null, json?.requestId ?? response.headers.get("x-request-id"), json?.details);
+        }
+        return { data: json.data, pagination: json.pagination };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createCommunityClient, newIdempotencyKey } from "./client.js";
+export type { CommunityClient, CommunityClientOptions, CreatePostInput, EditPostInput, FeedParams, PublishPostInput, } from "./client.js";
+export { CommunityApiError, isAbortError } from "./errors.js";
+export { communityKeys } from "./keys.js";
+export { xhrUploader } from "./upload.js";
+export type { FileUploader } from "./upload.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createCommunityClient, newIdempotencyKey } from "./client.js";
+export { CommunityApiError, isAbortError } from "./errors.js";
+export { communityKeys } from "./keys.js";
+export { xhrUploader } from "./upload.js";
+export * from "./types.js";

package/dist/keys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Query-key factories for TanStack Query. Every key starts with the community, so the caches of different PYQDeck
+ * apps can never mix, and `invalidateQueries({ queryKey: communityKeys.all("beu") })` clears one community cleanly.
+ * Keys hold only plain JSON, so they persist with the app's AsyncStorage persister.
+ */
+type Filters = Record<string, string | number | boolean | null | undefined>;
+export declare const communityKeys: {
+    all: (community: string) => readonly ["community", string];
+    info: (community: string) => readonly ["community", string, "info"];
+    feeds: (community: string) => readonly ["community", string, "feed"];
+    feed: (community: string, filters?: Filters) => readonly ["community", string, "feed", Filters];
+    post: (community: string, idOrSlug: string) => readonly ["community", string, "post", string];
+    comments: (community: string, postId: string) => readonly ["community", string, "comments", string];
+    replies: (community: string, commentId: string) => readonly ["community", string, "replies", string];
+    me: (community: string) => readonly ["community", string, "me"];
+    member: (community: string, username: string) => readonly ["community", string, "member", string];
+    memberPosts: (community: string, username: string) => readonly ["community", string, "member-posts", string];
+    bookmarks: (community: string) => readonly ["community", string, "bookmarks"];
+    notifications: (community: string, filters?: Filters) => readonly ["community", string, "notifications", Filters];
+    unreadCount: (community: string) => readonly ["community", string, "unread-count"];
+    trending: (community: string) => readonly ["community", string, "trending"];
+    search: (community: string, q: string) => readonly ["community", string, "search", string];
+    link: (community: string, code: string) => readonly ["community", string, "link", string];
+};
+export {};

package/dist/keys.js

@@ -0,0 +1,18 @@
+export const communityKeys = {
+    all: (community) => ["community", community],
+    info: (community) => [...communityKeys.all(community), "info"],
+    feeds: (community) => [...communityKeys.all(community), "feed"],
+    feed: (community, filters = {}) => [...communityKeys.feeds(community), filters],
+    post: (community, idOrSlug) => [...communityKeys.all(community), "post", idOrSlug],
+    comments: (community, postId) => [...communityKeys.all(community), "comments", postId],
+    replies: (community, commentId) => [...communityKeys.all(community), "replies", commentId],
+    me: (community) => [...communityKeys.all(community), "me"],
+    member: (community, username) => [...communityKeys.all(community), "member", username],
+    memberPosts: (community, username) => [...communityKeys.all(community), "member-posts", username],
+    bookmarks: (community) => [...communityKeys.all(community), "bookmarks"],
+    notifications: (community, filters = {}) => [...communityKeys.all(community), "notifications", filters],
+    unreadCount: (community) => [...communityKeys.all(community), "unread-count"],
+    trending: (community) => [...communityKeys.all(community), "trending"],
+    search: (community, q) => [...communityKeys.all(community), "search", q],
+    link: (community, code) => [...communityKeys.all(community), "link", code],
+};

package/dist/types.d.ts

@@ -0,0 +1,208 @@
+/** Shapes returned by the Community API. Dates are ISO strings so responses can be persisted as plain JSON. */
+export type Role = "member" | "moderator" | "admin";
+export type PostStatus = "published" | "pending" | "rejected" | "deleted";
+export type CommentStatus = PostStatus;
+export interface Author {
+    /** null only for a deleted member who has no row left to point at. */
+    id: string | null;
+    /** null for deleted members, who render as "Deleted user". */
+    username: string | null;
+    displayName: string;
+    avatarUrl: string;
+    headline: string;
+    role: Role;
+}
+export interface LinkRef {
+    code: string;
+    /** What readers see in the text, e.g. https://go.pyqdeck.in/aB3dE5gH */
+    shortUrl: string;
+    /** Destination host, to show next to the link. */
+    host: string;
+    /** Only present on your own content. */
+    clicks?: number;
+}
+export interface PostMedia {
+    id: string;
+    url: string;
+}
+export interface LinkedResource {
+    type: "pyq" | "topic";
+    title: string;
+    subtitle?: string;
+    subjectId?: string;
+    semesterId?: string;
+    year?: number;
+    questionId?: string;
+    topicId?: string;
+}
+export interface Post {
+    id: string;
+    slug: string;
+    author: Author;
+    /** The text readers see, with short links substituted. */
+    body: string;
+    hashtags: string[];
+    media: PostMedia[];
+    linkedResource: LinkedResource | null;
+    links: LinkRef[];
+    status: PostStatus;
+    likesCount: number;
+    commentsCount: number;
+    bookmarksCount: number;
+    isLiked: boolean;
+    isBookmarked: boolean;
+    isOwnPost: boolean;
+    editedAt: string | null;
+    createdAt: string;
+    /** The text as typed, for the edit form. */
+    rawBody?: string;
+    heldReason?: "moderation" | "reports" | null;
+    removedReason?: string | null;
+    hasPendingEdit?: boolean;
+}
+export interface Comment {
+    id: string;
+    postId: string;
+    /** The thread's top-level comment; null for a top-level comment itself. */
+    parentId: string | null;
+    author: Author;
+    replyTo: {
+        id: string | null;
+        username: string | null;
+        displayName: string;
+    } | null;
+    body: string;
+    links: LinkRef[];
+    status: CommentStatus;
+    likesCount: number;
+    repliesCount: number;
+    isLiked: boolean;
+    isOwn: boolean;
+    editedAt: string | null;
+    createdAt: string;
+    rawBody?: string;
+    hasPendingEdit?: boolean;
+}
+export interface Member extends Author {
+    coverUrl: string;
+    bio: string;
+    location: string;
+    github: string;
+    linkedin: string;
+    twitter: string;
+    website: string;
+    websiteLink: LinkRef | null;
+    skills: string[];
+    attributes: Record<string, string | number | boolean | null>;
+    followersCount: number;
+    followingCount: number;
+    postsCount: number;
+    upvotesCount: number;
+    joinedAt: string;
+    isFollowing?: boolean;
+}
+export interface OwnMember extends Member {
+    email: string;
+    status: "active" | "suspended" | "deleted";
+    suspendedUntil: string | null;
+    isPlatformAdmin: boolean;
+}
+export interface ProfileUpdate {
+    username?: string;
+    displayName?: string;
+    headline?: string;
+    bio?: string;
+    location?: string;
+    github?: string;
+    linkedin?: string;
+    twitter?: string;
+    website?: string;
+    skills?: string[];
+    attributes?: Record<string, string | number | boolean | null>;
+    /** Media ids from `media.uploadImages`; null removes the image. */
+    avatarMediaId?: string | null;
+    coverMediaId?: string | null;
+}
+export type NotificationType = "comment" | "reply" | "upvote" | "follow" | "moderation";
+export interface Notification {
+    id: string;
+    type: NotificationType;
+    title: string;
+    body: string;
+    read: boolean;
+    /** For aggregated upvotes: "received N new upvotes". */
+    count: number;
+    actor: Author | null;
+    target: {
+        type: "post" | "comment" | "member";
+        id: string | null;
+        postId: string | null;
+    } | null;
+    createdAt: string;
+}
+export interface TrendingTag {
+    tag: string;
+    count: number;
+}
+export interface CommunityInfo {
+    slug: string;
+    name: string;
+    status: "active" | "read_only" | "disabled";
+    limits: {
+        postMaxChars: number;
+        commentMaxChars: number;
+        maxImagesPerPost: number;
+        maxLinksPerPost: number;
+        maxLinksPerComment: number;
+    };
+}
+export interface MediaItem {
+    id: string;
+    url: string;
+    mimeType: string;
+    size: number;
+    status: "uploading" | "pending" | "attached";
+}
+export interface UploadTicket {
+    method: "POST";
+    url: string;
+    fields: Record<string, string | number>;
+    fileField: string;
+    expiresAt: string;
+}
+export type ReportReason = "spam" | "harassment" | "hate" | "sexual" | "violence" | "misinformation" | "other";
+export type ReportTarget = "post" | "comment" | "member" | "link";
+export interface ReportGroup {
+    targetType: ReportTarget;
+    targetId: string;
+    count: number;
+    reasons: ReportReason[];
+    notes: string[];
+    firstReportedAt: string;
+}
+export interface LinkInfo {
+    code: string;
+    host: string;
+    verdict: "clean" | "suspicious" | "malicious" | "unchecked";
+    status: "active" | "inactive" | "blocked";
+    /** What a tap would do: open at once, show the warning page, or refuse. */
+    decision: "redirect" | "warn" | "blocked" | "gone" | "notfound";
+}
+/** A cursor page. Pass `nextCursor` back to get the next one. */
+export interface Page<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+export interface PageParams {
+    cursor?: string;
+    limit?: number;
+}
+/** A picked image on the device, before it is uploaded. */
+export interface LocalImage {
+    uri: string;
+    mimeType: "image/jpeg" | "image/png" | "image/webp";
+    /** Bytes. Declared to the server up front so storage can be reserved. */
+    size: number;
+    name?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Shapes returned by the Community API. Dates are ISO strings so responses can be persisted as plain JSON. */
+export {};

package/dist/upload.d.ts

@@ -0,0 +1,14 @@
+import type { LocalImage, UploadTicket } from "./types.js";
+/** Sends one file to the storage provider with a signed ticket. Replaceable (tests, other runtimes). */
+export type FileUploader = (input: {
+    ticket: UploadTicket;
+    image: LocalImage;
+    /** Bytes sent so far and in total, for a progress bar. */
+    onProgress: (sent: number, total: number) => void;
+    signal?: AbortSignal;
+}) => Promise<void>;
+/**
+ * The default uploader. It uses XMLHttpRequest because that is the only way to get upload progress in React Native
+ * (`fetch` has none), and it appends the file as `{ uri, name, type }`, which React Native's FormData streams from disk.
+ */
+export declare const xhrUploader: FileUploader;

package/dist/upload.js

@@ -0,0 +1,35 @@
+/// <reference lib="dom" />
+import { CommunityApiError } from "./errors.js";
+/**
+ * The default uploader. It uses XMLHttpRequest because that is the only way to get upload progress in React Native
+ * (`fetch` has none), and it appends the file as `{ uri, name, type }`, which React Native's FormData streams from disk.
+ */
+export const xhrUploader = ({ ticket, image, onProgress, signal }) => new Promise((resolve, reject) => {
+    const form = new FormData();
+    for (const [key, value] of Object.entries(ticket.fields))
+        form.append(key, String(value));
+    form.append(ticket.fileField, {
+        uri: image.uri,
+        name: image.name ?? "photo",
+        type: image.mimeType,
+    });
+    const xhr = new XMLHttpRequest();
+    xhr.open(ticket.method, ticket.url);
+    xhr.upload.onprogress = (e) => e.lengthComputable && onProgress(e.loaded, e.total);
+    xhr.onload = () => {
+        if (xhr.status >= 200 && xhr.status < 300)
+            return resolve();
+        reject(new CommunityApiError("The image could not be uploaded. Please try again.", xhr.status, "upload_failed"));
+    };
+    xhr.onerror = () => reject(new CommunityApiError("Could not reach the server. Check your connection.", 0, "network_error"));
+    xhr.ontimeout = () => reject(new CommunityApiError("The upload took too long. Please try again.", 0, "timeout"));
+    xhr.timeout = 120000;
+    const onAbort = () => {
+        xhr.abort();
+        reject(new CommunityApiError("Request cancelled", 0, "aborted"));
+    };
+    if (signal?.aborted)
+        return onAbort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    xhr.send(form);
+});

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@pyqdeck/community-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Typed client for the PYQDeck Community API (posts, comments, members, short links). No Clerk, React or cache inside: the app supplies the token and owns caching.",
+  "keywords": [
+    "pyqdeck",
+    "community",
+    "sdk",
+    "react-native",
+    "expo",
+    "tanstack-query"
+  ],
+  "license": "MIT",
+  "author": "Raiyan Hasan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasanraiyan/pyqdeck-community.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/hasanraiyan/pyqdeck-community/tree/master/sdk#readme",
+  "bugs": "https://github.com/hasanraiyan/pyqdeck-community/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.0"
+  }
+}