@hirely/sdk 1.0.1

package/dist/client.d.ts

@@ -0,0 +1,151 @@
+import type { HirelyConfig, HirelyPortfolio, HirelyMe, HirelyRequestOptions } from "./types.js";
+import type { ProjectsResource } from "./resources/projects.js";
+import type { WorkResource } from "./resources/work.js";
+import type { EducationResource } from "./resources/education.js";
+import type { SkillsResource } from "./resources/skills.js";
+import type { CertificatesResource } from "./resources/certificates.js";
+import type { ServicesResource } from "./resources/services.js";
+import type { TestimonialsResource } from "./resources/testimonials.js";
+import type { FaqsResource } from "./resources/faqs.js";
+import type { ContactsResource } from "./resources/contacts.js";
+import type { CvResource } from "./resources/cv.js";
+/**
+ * The Hirely SDK client.
+ *
+ * Instantiate once with your public API key and use any method or
+ * resource to fetch your portfolio data from the Hirely API.
+ *
+ * @example Basic usage
+ * ```ts
+ * import Hirely from "@hirely/sdk";
+ *
+ * const hirely = new Hirely({
+ *   apiKey: process.env.HIRELY_API_KEY!,
+ * });
+ *
+ * const portfolio = await hirely.get();
+ * const me        = await hirely.me();
+ * const project   = await hirely.projects.getBySlug("my-app");
+ * ```
+ *
+ * @example With caching and retries
+ * ```ts
+ * const hirely = new Hirely({
+ *   apiKey: process.env.HIRELY_API_KEY!,
+ *   timeout: 10_000,
+ *   retries: 2,
+ *   cache: { enabled: true, ttl: 300 },
+ * });
+ * ```
+ */
+export default class Hirely {
+    /**
+     * Projects resource.
+     * - `hirely.projects()` — all public projects
+     * - `hirely.projects.getById(id)` — fetch by MongoDB ID
+     * - `hirely.projects.getBySlug(slug)` — fetch by URL slug
+     */
+    readonly projects: ProjectsResource;
+    /**
+     * Work experience resource.
+     * - `hirely.work()` — all work experience entries
+     * - `hirely.work.getById(id)` — fetch a single entry
+     */
+    readonly work: WorkResource;
+    /**
+     * Education resource.
+     * - `hirely.education()` — all education entries
+     * - `hirely.education.getById(id)` — fetch a single entry
+     */
+    readonly education: EducationResource;
+    /**
+     * Skills resource.
+     * - `hirely.skills()` — all skills
+     */
+    readonly skills: SkillsResource;
+    /**
+     * Certificates resource.
+     * - `hirely.certificates()` — all certificates
+     * - `hirely.certificates.getById(id)` — fetch a single certificate
+     */
+    readonly certificates: CertificatesResource;
+    /**
+     * Services resource.
+     * - `hirely.services()` — all public services
+     * - `hirely.services.getById(id)` — fetch a single service
+     */
+    readonly services: ServicesResource;
+    /**
+     * Testimonials resource (approved and public only).
+     * - `hirely.testimonials()` — all testimonials
+     * - `hirely.testimonials.getById(id)` — fetch a single testimonial
+     */
+    readonly testimonials: TestimonialsResource;
+    /**
+     * FAQ resource.
+     * - `hirely.faqs()` — all FAQ entries
+     * - `hirely.faqs.getById(id)` — fetch a single FAQ
+     */
+    readonly faqs: FaqsResource;
+    /**
+     * Contacts resource.
+     * - `hirely.contacts()` — public social links
+     */
+    readonly contacts: ContactsResource;
+    /**
+     * CV resource.
+     * - `hirely.cv()` — most recent public CV
+     */
+    readonly cv: CvResource;
+    constructor(config: HirelyConfig);
+    /**
+     * Fetches the complete public portfolio in a single request.
+     *
+     * Returns profile, projects, work, education, skills, certificates,
+     * services, testimonials, FAQs, contacts, and CV.
+     *
+     * @param options - Optional per-request options.
+     *
+     * @example
+     * ```ts
+     * const portfolio = await hirely.get();
+     * console.log(portfolio.profile?.firstName);
+     * console.log(portfolio.projects.length);
+     * ```
+     *
+     * @example Next.js Server Component
+     * ```tsx
+     * export default async function Page() {
+     *   const portfolio = await hirely.get();
+     *   return (
+     *     <main>
+     *       <h1>{portfolio.profile?.firstName} {portfolio.profile?.lastName}</h1>
+     *       {portfolio.projects.map((p) => (
+     *         <article key={p._id}><h2>{p.title}</h2></article>
+     *       ))}
+     *     </main>
+     *   );
+     * }
+     * ```
+     */
+    get(options?: HirelyRequestOptions): Promise<HirelyPortfolio>;
+    /**
+     * Fetches account information and the full public profile.
+     *
+     * Returns account-level data (username, email, role, plan) plus the
+     * complete profile (name, bio, avatar, location, birthday, etc.).
+     *
+     * @param options - Optional per-request options.
+     *
+     * @example
+     * ```ts
+     * const me = await hirely.me();
+     * console.log(me.userName);              // "mahmoud"
+     * console.log(me.plan);                  // "pro"
+     * console.log(me.profile?.firstName);    // "Mahmoud"
+     * console.log(me.profile?.positionName); // "Full-Stack Developer"
+     * console.log(me.profile?.avatar?.url);  // "https://..."
+     * ```
+     */
+    me(options?: HirelyRequestOptions): Promise<HirelyMe>;
+}

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+/** Default request timeout in milliseconds. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** Default number of retry attempts for transient errors. */
+export declare const DEFAULT_RETRIES = 2;
+/** HTTP status codes that trigger a retry. */
+export declare const RETRYABLE_STATUS_CODES: Set<number>;
+/** Maximum backoff delay between retries in milliseconds. */
+export declare const MAX_BACKOFF_MS = 30000;

package/dist/errors.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Base class for all Hirely SDK errors.
+ *
+ * @example
+ * ```ts
+ * import { HirelyError } from "@hirely/sdk";
+ *
+ * try {
+ *   await hirely.get();
+ * } catch (error) {
+ *   if (error instanceof HirelyError) {
+ *     console.error(error.status, error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class HirelyError extends Error {
+    /** HTTP status code (0 for network/timeout errors). */
+    readonly status: number;
+    /** Machine-readable error code. */
+    readonly code: string;
+    /** The request ID from the server, if available. */
+    readonly requestId?: string;
+    constructor(message: string, status: number, code?: string, requestId?: string);
+}
+/**
+ * Thrown when the API key is missing, invalid, or revoked (HTTP 401/403).
+ *
+ * @example
+ * ```ts
+ * import { HirelyAuthenticationError } from "@hirely/sdk";
+ *
+ * try {
+ *   await hirely.get();
+ * } catch (error) {
+ *   if (error instanceof HirelyAuthenticationError) {
+ *     console.error("Check your HIRELY_API_KEY.");
+ *   }
+ * }
+ * ```
+ */
+export declare class HirelyAuthenticationError extends HirelyError {
+    constructor(message?: string, status?: number, requestId?: string);
+}
+/**
+ * Thrown when a requested resource does not exist (HTTP 404).
+ *
+ * @example
+ * ```ts
+ * import { HirelyNotFoundError } from "@hirely/sdk";
+ *
+ * try {
+ *   const project = await hirely.projects.getBySlug("nonexistent");
+ * } catch (error) {
+ *   if (error instanceof HirelyNotFoundError) {
+ *     console.log("Project not found");
+ *   }
+ * }
+ * ```
+ */
+export declare class HirelyNotFoundError extends HirelyError {
+    constructor(message?: string, requestId?: string);
+}
+/**
+ * Thrown when a request fails validation (HTTP 400/422).
+ */
+export declare class HirelyValidationError extends HirelyError {
+    constructor(message?: string, status?: number, requestId?: string);
+}
+/**
+ * Thrown when the API rate limit has been exceeded (HTTP 429).
+ *
+ * @example
+ * ```ts
+ * import { HirelyRateLimitError } from "@hirely/sdk";
+ *
+ * try {
+ *   await hirely.get();
+ * } catch (error) {
+ *   if (error instanceof HirelyRateLimitError) {
+ *     console.log(`Retry after ${error.retryAfter}s`);
+ *   }
+ * }
+ * ```
+ */
+export declare class HirelyRateLimitError extends HirelyError {
+    /** Seconds until the rate limit resets (from `Retry-After` header). */
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, requestId?: string);
+}
+/**
+ * Thrown when a request exceeds the configured timeout.
+ *
+ * @example
+ * ```ts
+ * const hirely = new Hirely({ apiKey, timeout: 5000 });
+ *
+ * try {
+ *   await hirely.get();
+ * } catch (error) {
+ *   if (error instanceof HirelyTimeoutError) {
+ *     console.error("Request timed out after 5s");
+ *   }
+ * }
+ * ```
+ */
+export declare class HirelyTimeoutError extends HirelyError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the Hirely API returns a server-side error (HTTP 5xx).
+ */
+export declare class HirelyServerError extends HirelyError {
+    constructor(message?: string, status?: number, requestId?: string);
+}

package/dist/http/request.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @hirely/sdk — Official JavaScript & TypeScript SDK for Hirely.
+ *
+ * @example
+ * ```ts
+ * import Hirely from "@hirely/sdk";
+ *
+ * const hirely = new Hirely({ apiKey: process.env.HIRELY_API_KEY! });
+ *
+ * const portfolio = await hirely.get();
+ * const me        = await hirely.me();
+ * const project   = await hirely.projects.getBySlug("my-app");
+ * ```
+ *
+ * @module
+ */
+export { default } from "./client.js";
+export { default as Hirely } from "./client.js";
+export { HirelyError, HirelyAuthenticationError, HirelyNotFoundError, HirelyValidationError, HirelyRateLimitError, HirelyTimeoutError, HirelyServerError, } from "./errors.js";
+export type { HirelyConfig, HirelyCacheConfig, HirelyCache, HirelyRequestOptions, HirelyPortfolio, HirelyMe, HirelyProfile, HirelyProject, HirelyProjectMedia, HirelyWork, HirelyEducation, HirelySkill, HirelyCertificate, HirelyService, HirelyTestimonial, HirelyTestimonialClient, HirelyFaq, HirelyContact, HirелySocialLink, HirelyCV, } from "./types.js";
+export type { ProjectsResource } from "./resources/projects.js";
+export type { WorkResource } from "./resources/work.js";
+export type { EducationResource } from "./resources/education.js";
+export type { SkillsResource } from "./resources/skills.js";
+export type { CertificatesResource } from "./resources/certificates.js";
+export type { ServicesResource } from "./resources/services.js";
+export type { TestimonialsResource } from "./resources/testimonials.js";
+export type { FaqsResource } from "./resources/faqs.js";
+export type { ContactsResource } from "./resources/contacts.js";
+export type { CvResource } from "./resources/cv.js";

package/dist/index.js

@@ -0,0 +1 @@
+export{s as Hirely,c as HirelyAuthenticationError,l as HirelyError,y as HirelyNotFoundError,p as HirelyRateLimitError,a as HirelyServerError,H as HirelyTimeoutError,u as HirelyValidationError,o as default};

package/dist/resources/certificates.d.ts

@@ -0,0 +1,25 @@
+import type { HirelyCertificate, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching certificates and credentials.
+ *
+ * ```ts
+ * const certs = await hirely.certificates();
+ * const cert  = await hirely.certificates.getById("665...");
+ * ```
+ */
+export interface CertificatesResource {
+    /**
+     * Fetches all certificates, sorted by issue date descending.
+     *
+     * @param options - Optional per-request options.
+     */
+    (options?: HirelyRequestOptions): Promise<HirelyCertificate[]>;
+    /**
+     * Fetches a single certificate by its MongoDB ID.
+     *
+     * @param id - The certificate's `_id` string.
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no certificate with that ID exists.
+     */
+    getById(id: string, options?: HirelyRequestOptions): Promise<HirelyCertificate>;
+}

package/dist/resources/contacts.d.ts

@@ -0,0 +1,15 @@
+import type { HirelyContact, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching public contact information (social links).
+ *
+ * @returns The contact entry, or `null` if none has been set up.
+ *
+ * @example
+ * ```ts
+ * const contact = await hirely.contacts();
+ * contact?.socialLinks?.forEach(link => {
+ *   console.log(link.platform, link.url);
+ * });
+ * ```
+ */
+export type ContactsResource = (options?: HirelyRequestOptions) => Promise<HirelyContact | null>;

package/dist/resources/cv.d.ts

@@ -0,0 +1,15 @@
+import type { HirelyCV, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching the most recent public CV (résumé).
+ *
+ * @returns The CV with download URLs, or `null` if no public CV exists.
+ *
+ * @example
+ * ```ts
+ * const cv = await hirely.cv();
+ * if (cv?.pdfUrl) {
+ *   console.log("Download PDF:", cv.pdfUrl);
+ * }
+ * ```
+ */
+export type CvResource = (options?: HirelyRequestOptions) => Promise<HirelyCV | null>;

package/dist/resources/education.d.ts

@@ -0,0 +1,25 @@
+import type { HirelyEducation, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching education history.
+ *
+ * ```ts
+ * const education = await hirely.education();
+ * const entry     = await hirely.education.getById("665...");
+ * ```
+ */
+export interface EducationResource {
+    /**
+     * Fetches all education entries, sorted by start date descending.
+     *
+     * @param options - Optional per-request options.
+     */
+    (options?: HirelyRequestOptions): Promise<HirelyEducation[]>;
+    /**
+     * Fetches a single education entry by its MongoDB ID.
+     *
+     * @param id - The education entry's `_id` string.
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no entry with that ID exists.
+     */
+    getById(id: string, options?: HirelyRequestOptions): Promise<HirelyEducation>;
+}

package/dist/resources/faqs.d.ts

@@ -0,0 +1,25 @@
+import type { HirelyFaq, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching FAQ entries.
+ *
+ * ```ts
+ * const faqs = await hirely.faqs();
+ * const faq  = await hirely.faqs.getById("665...");
+ * ```
+ */
+export interface FaqsResource {
+    /**
+     * Fetches all FAQ entries, sorted by creation date descending.
+     *
+     * @param options - Optional per-request options.
+     */
+    (options?: HirelyRequestOptions): Promise<HirelyFaq[]>;
+    /**
+     * Fetches a single FAQ entry by its MongoDB ID.
+     *
+     * @param id - The FAQ entry's `_id` string.
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no FAQ with that ID exists.
+     */
+    getById(id: string, options?: HirelyRequestOptions): Promise<HirelyFaq>;
+}

package/dist/resources/projects.d.ts

@@ -0,0 +1,51 @@
+import type { HirelyProject, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching projects.
+ *
+ * ```ts
+ * const projects = await hirely.projects();
+ * const project  = await hirely.projects.getById("665...");
+ * const project  = await hirely.projects.getBySlug("my-app");
+ * ```
+ */
+export interface ProjectsResource {
+    /**
+     * Fetches all public projects, sorted by featured then by creation date.
+     *
+     * @param options - Optional per-request options.
+     *
+     * @example
+     * ```ts
+     * const projects = await hirely.projects();
+     * console.log(projects[0].title);
+     * ```
+     */
+    (options?: HirelyRequestOptions): Promise<HirelyProject[]>;
+    /**
+     * Fetches a single project by its MongoDB ID.
+     *
+     * @param id - The project's `_id` string.
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no project with that ID exists.
+     *
+     * @example
+     * ```ts
+     * const project = await hirely.projects.getById("665f1a2b3c4d5e6f7a8b9c0d");
+     * ```
+     */
+    getById(id: string, options?: HirelyRequestOptions): Promise<HirelyProject>;
+    /**
+     * Fetches a single project by its URL slug.
+     *
+     * @param slug - The project's slug (e.g. `"my-awesome-app"`).
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no project with that slug exists.
+     *
+     * @example
+     * ```ts
+     * const project = await hirely.projects.getBySlug("my-awesome-app");
+     * console.log(project.technologies);
+     * ```
+     */
+    getBySlug(slug: string, options?: HirelyRequestOptions): Promise<HirelyProject>;
+}

package/dist/resources/services.d.ts

@@ -0,0 +1,25 @@
+import type { HirelyService, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching services offered by the portfolio owner.
+ *
+ * ```ts
+ * const services = await hirely.services();
+ * const service  = await hirely.services.getById("665...");
+ * ```
+ */
+export interface ServicesResource {
+    /**
+     * Fetches all public services, sorted by creation date descending.
+     *
+     * @param options - Optional per-request options.
+     */
+    (options?: HirelyRequestOptions): Promise<HirelyService[]>;
+    /**
+     * Fetches a single service by its MongoDB ID.
+     *
+     * @param id - The service's `_id` string.
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no service with that ID exists.
+     */
+    getById(id: string, options?: HirelyRequestOptions): Promise<HirelyService>;
+}

package/dist/resources/skills.d.ts

@@ -0,0 +1,22 @@
+import type { HirelySkill, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching skills.
+ *
+ * ```ts
+ * const skills = await hirely.skills();
+ * ```
+ */
+export interface SkillsResource {
+    /**
+     * Fetches all skills, sorted by creation date descending.
+     *
+     * @param options - Optional per-request options.
+     *
+     * @example
+     * ```ts
+     * const skills = await hirely.skills();
+     * const frontend = skills.filter(s => s.category === "Frontend");
+     * ```
+     */
+    (options?: HirelyRequestOptions): Promise<HirelySkill[]>;
+}

package/dist/resources/testimonials.d.ts

@@ -0,0 +1,26 @@
+import type { HirelyTestimonial, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching client testimonials.
+ * Only approved, public testimonials are returned.
+ *
+ * ```ts
+ * const testimonials = await hirely.testimonials();
+ * const testimonial  = await hirely.testimonials.getById("665...");
+ * ```
+ */
+export interface TestimonialsResource {
+    /**
+     * Fetches all approved public testimonials, sorted by creation date descending.
+     *
+     * @param options - Optional per-request options.
+     */
+    (options?: HirelyRequestOptions): Promise<HirelyTestimonial[]>;
+    /**
+     * Fetches a single testimonial by its MongoDB ID.
+     *
+     * @param id - The testimonial's `_id` string.
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no testimonial with that ID exists.
+     */
+    getById(id: string, options?: HirelyRequestOptions): Promise<HirelyTestimonial>;
+}

package/dist/resources/work.d.ts

@@ -0,0 +1,31 @@
+import type { HirelyWork, HirelyRequestOptions } from "../types.js";
+/**
+ * A callable resource for fetching work experience.
+ *
+ * ```ts
+ * const work = await hirely.work();
+ * const job  = await hirely.work.getById("665...");
+ * ```
+ */
+export interface WorkResource {
+    /**
+     * Fetches all work experience entries, sorted by start date descending.
+     *
+     * @param options - Optional per-request options.
+     *
+     * @example
+     * ```ts
+     * const jobs = await hirely.work();
+     * jobs.forEach(j => console.log(j.companyName, j.position));
+     * ```
+     */
+    (options?: HirelyRequestOptions): Promise<HirelyWork[]>;
+    /**
+     * Fetches a single work experience entry by its MongoDB ID.
+     *
+     * @param id - The work entry's `_id` string.
+     * @param options - Optional per-request options.
+     * @throws {HirelyNotFoundError} If no entry with that ID exists.
+     */
+    getById(id: string, options?: HirelyRequestOptions): Promise<HirelyWork>;
+}