naystack 1.5.9 → 1.5.11

package/dist/graphql/utils.d.ts

@@ -2,20 +2,29 @@ import { GraphQLScalarType } from 'graphql';
 import { ClassType, Query, Arg } from 'type-graphql';
 import { AuthorizedContext, Context } from './types.js';
 
+/** Options for @Query() / @Mutation() return type (e.g. nullable). */
 type ReturnOptions = Parameters<typeof Query>[1];
+/** Options for @Arg() (e.g. nullable). */
 type ArgsOptions = Parameters<typeof Arg>[2];
+/** Maps nullable keys to optional and normalizes null/undefined. */
 type NormalizeNullUndefined<T> = {
     [K in keyof T as null extends T[K] ? K : never]?: Exclude<T[K], undefined>;
 } & {
     [K in keyof T as null extends T[K] ? never : K]: undefined extends T[K] ? Exclude<T[K], undefined> | null : T[K];
 };
+/** Adds nullable option to Query/Arg options. */
 type NullableOptions<T, X extends boolean> = T & {
     nullable: X;
 };
+/** Resolves a GraphQL type (class, scalar, primitive) to TS type. */
 type ParsedGQLType<T, MergeNullUndefined extends boolean> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends GraphQLScalarType<infer U> ? U : T extends ClassType<infer U> ? MergeNullUndefined extends true ? NormalizeNullUndefined<U> : U : T extends Record<infer K, string | number> ? T[K] : void;
+/** Array-aware ParsedGQLType. */
 type ParsedGQLTypeWithArray<T, MergeNullUndefined extends boolean> = T extends Array<infer U> ? ParsedGQLType<U, MergeNullUndefined>[] : ParsedGQLType<T, MergeNullUndefined>;
+/** Adds null/undefined when nullable. */
 type ParsedGQLTypeWithNullability<T, IsNullable extends boolean, MergeNullUndefined extends boolean> = IsNullable extends true ? ParsedGQLTypeWithArray<T, MergeNullUndefined> | null | undefined : ParsedGQLTypeWithArray<T, MergeNullUndefined>;
+/** Allows resolver to return T or Promise<T>. */
 type Promisify<T> = T | Promise<T>;
+/** Base for query/field definition (output, input, options). */
 interface BaseDefinition<T, U, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false> {
     output: T;
     outputOptions?: NullableOptions<ReturnOptions, OutputNullable>;
@@ -23,26 +32,234 @@ interface BaseDefinition<T, U, IsAuth extends boolean = false, OutputNullable ex
     inputOptions?: NullableOptions<ArgsOptions, InputNullable>;
     authorized?: IsAuth;
 }
+/**
+ * Full query/mutation definition returned by {@link query}. Contains the resolver function,
+ * plus `.call()` and `.authCall()` for direct server-side invocation.
+ *
+ * @category GraphQL
+ */
 interface QueryDefinition<T, U, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>> extends BaseDefinition<T, U, IsAuth, OutputNullable, InputNullable> {
     fn: (ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R;
+    /** Calls the resolver server-side. For authorized queries, reads the refresh cookie; for non-authorized, passes null userId. */
     call: (data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
+    /** Calls the resolver server-side with authentication (always reads the refresh cookie). Use in Server Components. */
     authCall: (data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
     mutation?: boolean;
 }
+/**
+ * Defines a type-graphql query or mutation with typed input/output and optional auth.
+ * Use with {@link QueryLibrary} to build resolver classes for `initGraphQLServer`.
+ *
+ * Each query definition gets `.call(data)` and `.authCall(data)` methods for direct server-side invocation
+ * (e.g. in Server Components or other resolvers). Both are cached via React's `cache()`.
+ *
+ * @param fn - Resolver function: `(ctx, data) => result`.
+ *   - `ctx` is `Context` (or `AuthorizedContext` when `authorized: true`) with `userId`.
+ *   - `data` is the typed GraphQL input (or `void` if no input).
+ * @param options - Configuration for the query/mutation.
+ * @param options.output - The GraphQL return type (type-graphql `@ObjectType` class, `String`, `Boolean`, `Number`, etc.).
+ * @param options.input - Optional GraphQL input type (`@InputType` class or scalar) for the `input` argument.
+ * @param options.outputOptions - Optional. Set `{ nullable: true }` to allow null returns.
+ * @param options.inputOptions - Optional. Set `{ nullable: true }` to allow null input.
+ * @param options.authorized - If `true`, the resolver requires an authenticated user. `ctx` is typed as `AuthorizedContext` (non-null `userId`).
+ * @param options.mutation - If `true`, registers as a `@Mutation`; otherwise registers as a `@Query`.
+ * @returns A `QueryDefinition` with `.call(data)` and `.authCall(data)` for server-side invocation.
+ *
+ * @example Simple query (no input, nullable output):
+ * ```ts
+ * import { query } from "naystack/graphql";
+ *
+ * export default query(
+ *   async (ctx) => {
+ *     if (!ctx.userId) return null;
+ *     const [user] = await db.select().from(UserTable).where(eq(UserTable.id, ctx.userId));
+ *     return user || null;
+ *   },
+ *   { output: User, outputOptions: { nullable: true } },
+ * );
+ * ```
+ *
+ * @example Mutation with input and authorization:
+ * ```ts
+ * export default query(
+ *   async (ctx, input: SubmitFeedbackInput) => {
+ *     await db.insert(FeedbackTable).values({ userId: ctx.userId, score: input.score, text: input.text });
+ *     return true;
+ *   },
+ *   { output: Boolean, input: SubmitFeedbackInput, authorized: true, mutation: true },
+ * );
+ * ```
+ *
+ * @example Server-side invocation in a Server Component:
+ * ```ts
+ * const user = await getCurrentUser.authCall();   // Reads refresh cookie for auth
+ * const planets = await getPlanets.call();         // No auth needed
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function query<T, U, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>>(fn: (ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R, options: Omit<QueryDefinition<T, U, IsAuth, OutputNullable, InputNullable, R>, "fn" | "authCall" | "call">): QueryDefinition<T, U, IsAuth, OutputNullable, InputNullable, R>;
+/**
+ * Full field resolver definition returned by {@link field}. Contains the resolver function,
+ * plus `.call()` and `.authCall()` for direct server-side invocation.
+ *
+ * @category GraphQL
+ */
 interface FieldResolverDefinition<T, U, Root, IsAuth extends boolean = false, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>> extends BaseDefinition<T, U, IsAuth, OutputNullable, InputNullable> {
     fn: (root: Root, ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R;
+    /** Calls the field resolver server-side. For authorized fields, reads the refresh cookie. */
     call: (root: Root, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
+    /** Calls the field resolver server-side with authentication (always reads the refresh cookie). */
     authCall: (root: Root, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => Promise<Awaited<R>>;
 }
+/**
+ * Defines a type-graphql field resolver with typed root, context, and input.
+ * Use with {@link FieldLibrary} to attach computed fields to a parent GraphQL type.
+ *
+ * Like `query()`, each field definition gets `.call(root, data)` and `.authCall(root, data)` for server-side invocation.
+ *
+ * @param fn - Resolver function: `(root, ctx, data) => result`.
+ *   - `root` is the parent object (e.g. the `User` row from the database).
+ *   - `ctx` is `Context` (or `AuthorizedContext` when `authorized: true`).
+ *   - `data` is the optional typed input argument.
+ * @param options - Configuration (same as `query()` but without `mutation`).
+ * @returns A `FieldResolverDefinition` with `.call` and `.authCall` for server-side invocation.
+ *
+ * @example
+ * ```ts
+ * import { field } from "naystack/graphql";
+ *
+ * // Resolve the "seller" field on a Property type
+ * const seller = field(
+ *   async (property: PropertyDB) => {
+ *     if (!property.sellerId) return null;
+ *     const [seller] = await db.select().from(ContactTable).where(eq(ContactTable.id, property.sellerId));
+ *     return seller || null;
+ *   },
+ *   { output: ContactGQL, outputOptions: { nullable: true } },
+ * );
+ * ```
+ *
+ * @example Inline in a FieldLibrary:
+ * ```ts
+ * const OrgFields = FieldLibrary<OrgDB>(OrgGQL, {
+ *   access: field(
+ *     async (root, ctx) => {
+ *       if (!ctx.userId) return null;
+ *       return checkOrgAccess(ctx.userId, root.id);
+ *     },
+ *     { output: AccessRole, outputOptions: { nullable: true } },
+ *   ),
+ * });
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function field<T, U, IsAuth extends boolean, Root, OutputNullable extends boolean = false, InputNullable extends boolean = false, R extends Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>> = Promisify<ParsedGQLTypeWithNullability<T, OutputNullable, true>>>(fn: (root: Root, ctx: IsAuth extends true ? AuthorizedContext : Context, data: ParsedGQLTypeWithNullability<U, InputNullable, false>) => R, options: Omit<FieldResolverDefinition<T, U, Root, IsAuth, OutputNullable, InputNullable, R>, "fn" | "authCall" | "call">): FieldResolverDefinition<T, U, Root, IsAuth, OutputNullable, InputNullable, R>;
+/**
+ * Builds a type-graphql `@Resolver` class from a map of query/mutation definitions created with {@link query}.
+ * Each key in the `queries` object becomes a Query or Mutation field on the GraphQL schema.
+ *
+ * Pass the returned class in the `resolvers` array of `initGraphQLServer`.
+ *
+ * @param queries - Object mapping GraphQL field names to `QueryDefinition`s (from `query()`).
+ *   Each key becomes the field name in the schema. Mutations are determined by `{ mutation: true }` in the definition.
+ * @returns A `@Resolver` class suitable for `initGraphQLServer`.
+ *
+ * @example
+ * ```ts
+ * import { QueryLibrary, query } from "naystack/graphql";
+ * import getCurrentUser from "./resolvers/get-current-user";
+ * import updateUser from "./resolvers/update-user";
+ * import onboardUser from "./resolvers/onboard-user";
+ *
+ * export const UserResolvers = QueryLibrary({
+ *   getCurrentUser,  // becomes Query.getCurrentUser
+ *   updateUser,      // becomes Mutation.updateUser (if mutation: true)
+ *   onboardUser,     // becomes Mutation.onboardUser (if mutation: true)
+ * });
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function QueryLibrary<T extends Record<string, QueryDefinition<any, any, any, any, any, any>>>(queries: T): {
     new (): {};
 };
+/**
+ * Builds a type-graphql `@Resolver(() => type)` class that resolves computed fields on a parent GraphQL type.
+ * Each key in the `queries` object becomes a `@FieldResolver` on that type.
+ *
+ * Pass the returned class in the `resolvers` array of `initGraphQLServer`.
+ *
+ * @typeParam X - The database/plain type of the parent object (e.g. `UserDB`).
+ * @param type - The parent GraphQL type class (e.g. `User`). Must be a `@ObjectType` class.
+ * @param queries - Object mapping field names to `FieldResolverDefinition`s (from `field()`).
+ * @returns A `@Resolver` class for the given type; pass it in `initGraphQLServer`'s resolvers array.
+ *
+ * @example
+ * ```ts
+ * import { FieldLibrary, field } from "naystack/graphql";
+ * import { User } from "./types";
+ * import type { UserDB } from "./db";
+ * import organizations from "./resolvers/organizations-field";
+ *
+ * export const UserFieldResolvers = FieldLibrary<UserDB>(User, {
+ *   organizations,   // Resolves User.organizations from the UserDB row
+ * });
+ * ```
+ *
+ * @example With inline field definitions:
+ * ```ts
+ * export const OrgFieldResolvers = FieldLibrary<OrgDB>(OrgGQL, {
+ *   access: field(
+ *     async (root, ctx) => checkOrgAccess(ctx.userId, root.id),
+ *     { output: AccessRole, outputOptions: { nullable: true } },
+ *   ),
+ * });
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function FieldLibrary<X extends object, T extends Record<string, FieldResolverDefinition<any, any, X, any, any, any, any>> = Record<string, FieldResolverDefinition<any, any, X, any, any, any, any>>>(type: ClassType, queries: T): {
     new (): {};
 };
+/**
+ * Infers the TypeScript return type of a query definition's `.call()` method.
+ * Use this to type component props that receive query results, ensuring full type safety.
+ *
+ * @typeParam T - A `QueryDefinition` (the default export from a resolver file created with `query()`).
+ *
+ * @example
+ * ```ts
+ * import type { QueryResponseType } from "naystack/graphql";
+ * import type getCurrentUser from "@/app/api/(graphql)/User/resolvers/get-current-user";
+ * import type getDeal from "@/app/api/(graphql)/Deal/queries/get-deal";
+ *
+ * interface Props {
+ *   user: QueryResponseType<typeof getCurrentUser>;
+ *   deal: QueryResponseType<typeof getDeal>;
+ * }
+ * ```
+ *
+ * @category GraphQL
+ */
 type QueryResponseType<T extends QueryDefinition<any, any, any, any, any, any>> = Awaited<ReturnType<T["call"]>>;
+/**
+ * Infers the TypeScript return type of a field resolver definition's `.call()` method.
+ * Use this to type the resolved field value.
+ *
+ * @typeParam T - A `FieldResolverDefinition` (from `field()`).
+ *
+ * @example
+ * ```ts
+ * import type { FieldResponseType } from "naystack/graphql";
+ * import type organizationsField from "./resolvers/organizations-field";
+ *
+ * type Orgs = FieldResponseType<typeof organizationsField>;
+ * ```
+ *
+ * @category GraphQL
+ */
 type FieldResponseType<T extends FieldResolverDefinition<any, any, any, any, any, any, any>> = Awaited<ReturnType<T["call"]>>;
 
 export { FieldLibrary, type FieldResponseType, QueryLibrary, type QueryResponseType, field, query };

package/dist/index.d.mts

@@ -1,3 +1,19 @@
+/**
+ * Naystack — a minimal, powerful stack for Next.js app development.
+ *
+ * Use subpath imports for the specific module you need:
+ * - `naystack/auth` — Email/Google/Instagram authentication
+ * - `naystack/auth/email/client` — Client-side auth hooks (useLogin, useSignUp, etc.)
+ * - `naystack/graphql` — GraphQL server: query, field, QueryLibrary, FieldLibrary, initGraphQLServer
+ * - `naystack/graphql/client` — Client-side GraphQL hooks (useAuthQuery, useAuthMutation, ApolloWrapper)
+ * - `naystack/graphql/server` — Server-side GraphQL utilities (Injector, query)
+ * - `naystack/file` — S3 file upload setup
+ * - `naystack/file/client` — Client-side file upload hook (useFileUpload)
+ * - `naystack/client` — Client hooks (useVisibility, useBreakpoint) and SEO (setupSEO)
+ * - `naystack/socials` — Instagram and Threads API helpers
+ *
+ * @module
+ */
 declare const hello = "world";
 
 export { hello };

package/dist/index.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Naystack — a minimal, powerful stack for Next.js app development.
+ *
+ * Use subpath imports for the specific module you need:
+ * - `naystack/auth` — Email/Google/Instagram authentication
+ * - `naystack/auth/email/client` — Client-side auth hooks (useLogin, useSignUp, etc.)
+ * - `naystack/graphql` — GraphQL server: query, field, QueryLibrary, FieldLibrary, initGraphQLServer
+ * - `naystack/graphql/client` — Client-side GraphQL hooks (useAuthQuery, useAuthMutation, ApolloWrapper)
+ * - `naystack/graphql/server` — Server-side GraphQL utilities (Injector, query)
+ * - `naystack/file` — S3 file upload setup
+ * - `naystack/file/client` — Client-side file upload hook (useFileUpload)
+ * - `naystack/client` — Client hooks (useVisibility, useBreakpoint) and SEO (setupSEO)
+ * - `naystack/socials` — Instagram and Threads API helpers
+ *
+ * @module
+ */
 declare const hello = "world";
 
 export { hello };

package/dist/socials/instagram/getters.d.mts

@@ -1,9 +1,71 @@
 import { InstagramConversation, InstagramError, InstagramMedia, InstagramMessage, InstagramUser } from './types.mjs';
 
+/**
+ * Fetches an Instagram user's profile. Defaults to the authenticated user (`"me"`).
+ *
+ * @param token - Instagram access token.
+ * @param id - User id to fetch. Defaults to `"me"` (the token owner).
+ * @param fields - Optional array of field names to request. Default: `["username", "followers_count", "media_count"]`.
+ * @returns Promise of user data (typed as `T`, defaults to {@link InstagramUser}).
+ *
+ * @example
+ * ```ts
+ * import { getInstagramUser } from "naystack/socials";
+ *
+ * const user = await getInstagramUser(accessToken);
+ * console.log(user?.username, user?.followers_count);
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramUser: <T = InstagramUser>(token: string, id?: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
+/**
+ * Fetches the authenticated user's recent Instagram media.
+ *
+ * @param token - Instagram access token.
+ * @param fields - Optional array of field names. Default: `["like_count", "comments_count", "permalink"]`.
+ * @param limit - Maximum number of items to return. Default: `12`.
+ * @returns Promise of `{ data: T[] }` where T defaults to {@link InstagramMedia}.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramMedia } from "naystack/socials";
+ *
+ * const media = await getInstagramMedia(accessToken, undefined, 10);
+ * for (const item of media?.data ?? []) {
+ *   console.log(item.permalink, item.like_count);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramMedia: <T = InstagramMedia>(token: string, fields?: string[], limit?: number) => Promise<({
     data: T[];
 } & InstagramError) | null>;
+/**
+ * Fetches Instagram conversations (DM threads) with pagination support.
+ *
+ * @param token - Instagram access token.
+ * @param limit - Page size. Default: `25`.
+ * @param cursor - Optional pagination cursor (from a previous `fetchMore`).
+ * @returns Promise of `{ data: InstagramConversation[], fetchMore?: () => Promise<...> }`.
+ *   Call `fetchMore()` to load the next page.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversations } from "naystack/socials";
+ *
+ * const convos = await getInstagramConversations(accessToken, 25);
+ * for (const convo of convos.data ?? []) {
+ *   console.log(convo.participants, convo.messages);
+ * }
+ * if (convos.fetchMore) {
+ *   const nextPage = await convos.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversations: (token: string, limit?: number, cursor?: string) => Promise<{
     data: {
         messages: {
@@ -19,10 +81,53 @@ declare const getInstagramConversations: (token: string, limit?: number, cursor?
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches conversations filtered by a specific Instagram user id.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The Instagram user id to filter conversations by.
+ * @returns Promise of `{ data: InstagramConversation[] }`.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationsByUser: (token: string, userID: string) => Promise<({
     data: InstagramConversation[];
 } & InstagramError) | null>;
+/**
+ * Fetches the single conversation between the authenticated user and the given user.
+ * Filters for conversations with exactly 2 participants.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The other participant's Instagram user id.
+ * @returns Promise of a single `InstagramConversation` or `undefined` if not found.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationByUser: (token: string, userID: string) => Promise<InstagramConversation | undefined>;
+/**
+ * Fetches a single Instagram conversation by id with messages and participants.
+ * Supports pagination for messages via `fetchMore`.
+ *
+ * @param token - Instagram access token.
+ * @param id - Conversation id.
+ * @param cursor - Optional pagination cursor for messages.
+ * @returns Promise of `{ messages, participants, fetchMore? }`.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversation } from "naystack/socials";
+ *
+ * const convo = await getInstagramConversation(accessToken, conversationId);
+ * for (const msg of convo.messages ?? []) {
+ *   console.log(msg.id, msg.created_time);
+ * }
+ * if (convo.fetchMore) {
+ *   const older = await convo.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversation: (token: string, id: string, cursor?: string) => Promise<{
     messages: {
         id: string;
@@ -34,6 +139,16 @@ declare const getInstagramConversation: (token: string, id: string, cursor?: str
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches a single Instagram message by id.
+ *
+ * @param token - Instagram access token.
+ * @param id - Message id.
+ * @param fields - Optional array of field names. Default: `["id", "created_time", "from", "to", "message"]`.
+ * @returns Promise of message data (typed as `T`, defaults to {@link InstagramMessage}).
+ *
+ * @category Socials
+ */
 declare const getInstagramMessage: <T = InstagramMessage>(token: string, id: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
 
 export { getInstagramConversation, getInstagramConversationByUser, getInstagramConversations, getInstagramConversationsByUser, getInstagramMedia, getInstagramMessage, getInstagramUser };

package/dist/socials/instagram/getters.d.ts

@@ -1,9 +1,71 @@
 import { InstagramConversation, InstagramError, InstagramMedia, InstagramMessage, InstagramUser } from './types.js';
 
+/**
+ * Fetches an Instagram user's profile. Defaults to the authenticated user (`"me"`).
+ *
+ * @param token - Instagram access token.
+ * @param id - User id to fetch. Defaults to `"me"` (the token owner).
+ * @param fields - Optional array of field names to request. Default: `["username", "followers_count", "media_count"]`.
+ * @returns Promise of user data (typed as `T`, defaults to {@link InstagramUser}).
+ *
+ * @example
+ * ```ts
+ * import { getInstagramUser } from "naystack/socials";
+ *
+ * const user = await getInstagramUser(accessToken);
+ * console.log(user?.username, user?.followers_count);
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramUser: <T = InstagramUser>(token: string, id?: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
+/**
+ * Fetches the authenticated user's recent Instagram media.
+ *
+ * @param token - Instagram access token.
+ * @param fields - Optional array of field names. Default: `["like_count", "comments_count", "permalink"]`.
+ * @param limit - Maximum number of items to return. Default: `12`.
+ * @returns Promise of `{ data: T[] }` where T defaults to {@link InstagramMedia}.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramMedia } from "naystack/socials";
+ *
+ * const media = await getInstagramMedia(accessToken, undefined, 10);
+ * for (const item of media?.data ?? []) {
+ *   console.log(item.permalink, item.like_count);
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramMedia: <T = InstagramMedia>(token: string, fields?: string[], limit?: number) => Promise<({
     data: T[];
 } & InstagramError) | null>;
+/**
+ * Fetches Instagram conversations (DM threads) with pagination support.
+ *
+ * @param token - Instagram access token.
+ * @param limit - Page size. Default: `25`.
+ * @param cursor - Optional pagination cursor (from a previous `fetchMore`).
+ * @returns Promise of `{ data: InstagramConversation[], fetchMore?: () => Promise<...> }`.
+ *   Call `fetchMore()` to load the next page.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversations } from "naystack/socials";
+ *
+ * const convos = await getInstagramConversations(accessToken, 25);
+ * for (const convo of convos.data ?? []) {
+ *   console.log(convo.participants, convo.messages);
+ * }
+ * if (convos.fetchMore) {
+ *   const nextPage = await convos.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversations: (token: string, limit?: number, cursor?: string) => Promise<{
     data: {
         messages: {
@@ -19,10 +81,53 @@ declare const getInstagramConversations: (token: string, limit?: number, cursor?
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches conversations filtered by a specific Instagram user id.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The Instagram user id to filter conversations by.
+ * @returns Promise of `{ data: InstagramConversation[] }`.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationsByUser: (token: string, userID: string) => Promise<({
     data: InstagramConversation[];
 } & InstagramError) | null>;
+/**
+ * Fetches the single conversation between the authenticated user and the given user.
+ * Filters for conversations with exactly 2 participants.
+ *
+ * @param token - Instagram access token.
+ * @param userID - The other participant's Instagram user id.
+ * @returns Promise of a single `InstagramConversation` or `undefined` if not found.
+ *
+ * @category Socials
+ */
 declare const getInstagramConversationByUser: (token: string, userID: string) => Promise<InstagramConversation | undefined>;
+/**
+ * Fetches a single Instagram conversation by id with messages and participants.
+ * Supports pagination for messages via `fetchMore`.
+ *
+ * @param token - Instagram access token.
+ * @param id - Conversation id.
+ * @param cursor - Optional pagination cursor for messages.
+ * @returns Promise of `{ messages, participants, fetchMore? }`.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramConversation } from "naystack/socials";
+ *
+ * const convo = await getInstagramConversation(accessToken, conversationId);
+ * for (const msg of convo.messages ?? []) {
+ *   console.log(msg.id, msg.created_time);
+ * }
+ * if (convo.fetchMore) {
+ *   const older = await convo.fetchMore();
+ * }
+ * ```
+ *
+ * @category Socials
+ */
 declare const getInstagramConversation: (token: string, id: string, cursor?: string) => Promise<{
     messages: {
         id: string;
@@ -34,6 +139,16 @@ declare const getInstagramConversation: (token: string, id: string, cursor?: str
     }[] | undefined;
     fetchMore: (() => Promise</*elided*/ any>) | undefined;
 }>;
+/**
+ * Fetches a single Instagram message by id.
+ *
+ * @param token - Instagram access token.
+ * @param id - Message id.
+ * @param fields - Optional array of field names. Default: `["id", "created_time", "from", "to", "message"]`.
+ * @returns Promise of message data (typed as `T`, defaults to {@link InstagramMessage}).
+ *
+ * @category Socials
+ */
 declare const getInstagramMessage: <T = InstagramMessage>(token: string, id: string, fields?: string[]) => Promise<(T & InstagramError) | null>;
 
 export { getInstagramConversation, getInstagramConversationByUser, getInstagramConversations, getInstagramConversationsByUser, getInstagramMedia, getInstagramMessage, getInstagramUser };

package/dist/socials/instagram/setters.d.mts

@@ -1,5 +1,23 @@
 import { InstagramError } from './types.mjs';
 
+/**
+ * Sends a text message to an Instagram user via the Instagram Messaging API.
+ *
+ * @param token - Instagram access token.
+ * @param to - Recipient's Instagram user id.
+ * @param text - Message text to send.
+ * @returns Promise of `{ recipient_id, message_id }` on success.
+ *
+ * @example
+ * ```ts
+ * import { sendInstagramMessage } from "naystack/socials";
+ *
+ * const result = await sendInstagramMessage(accessToken, recipientId, "Hello!");
+ * console.log("Sent message:", result?.message_id);
+ * ```
+ *
+ * @category Socials
+ */
 declare const sendInstagramMessage: (token: string, to: string, text: string) => Promise<({
     recipient_id?: string;
     message_id?: string;

package/dist/socials/instagram/setters.d.ts

@@ -1,5 +1,23 @@
 import { InstagramError } from './types.js';
 
+/**
+ * Sends a text message to an Instagram user via the Instagram Messaging API.
+ *
+ * @param token - Instagram access token.
+ * @param to - Recipient's Instagram user id.
+ * @param text - Message text to send.
+ * @returns Promise of `{ recipient_id, message_id }` on success.
+ *
+ * @example
+ * ```ts
+ * import { sendInstagramMessage } from "naystack/socials";
+ *
+ * const result = await sendInstagramMessage(accessToken, recipientId, "Hello!");
+ * console.log("Sent message:", result?.message_id);
+ * ```
+ *
+ * @category Socials
+ */
 declare const sendInstagramMessage: (token: string, to: string, text: string) => Promise<({
     recipient_id?: string;
     message_id?: string;