blocket.js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Philip Rutberg
+
+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

@@ -0,0 +1,109 @@
+# blocket.js
+
+blocket.js is a lightweight and easy-to-use npm package that provides a TypeScript interface to the unofficial Blocket API. It allows you to search and retrieve ads from blocket.se with automatic token management and error handling, so you can focus on building your application without worrying about the underlying API token management.
+
+## Features
+
+- **Simple API**: Import the client and call methods like `find` directly.
+- **Automatic Token Management**: Handles token retrieval, caching, and refreshing automatically when a token expires (detected via 401 errors).
+- **Configurable**: Global and per-request configuration options let you override API endpoints, logging preferences, retry attempts, and more.
+- **TypeScript Support**: Fully typed interfaces for query parameters, API responses, and advertisements.
+- **Robust Error Handling & Logging**: Automatic retries on token expiry with configurable logging to assist in debugging.
+
+## Installation
+
+Install blocket.js via npm:
+
+```bash
+npm install blocket.js
+```
+
+or using yarn:
+
+```bash
+yarn add blocket.js
+```
+
+## Usage
+
+### Basic Usage
+
+After installing the package, import the client and start using its methods immediately:
+
+```ts
+import client from 'blocket.js';
+
+(async () => {
+  try {
+    const ads = await client.find({ query: 'macbook air' });
+    console.log(ads);
+  } catch (error) {
+    console.error('Error fetching ads:', error);
+  }
+})();
+```
+
+### Advanced Usage
+
+#### Global Configuration
+
+Customize the package behavior with the global configuration. This allows you to override default values such as the API base URL, token endpoint, log level, and retry attempts.
+
+```ts
+import client, { configure } from 'blocket.js';
+
+configure({
+  apiBaseUrl: 'https://api.blocket.se/v1', // API base URL (default)
+  tokenEndpoint:
+    'https://www.blocket.se/api/adout-api-route/refresh-token-and-validate-session', // Token endpoint
+  logLevel: 'debug', // Options: 'none', 'error', 'info', 'debug'
+  retryAttempts: 3, // Maximum retry attempts on 401 errors
+});
+
+(async () => {
+  try {
+    const ads = await client.find({ query: 'macbook air', limit: 10 });
+    console.log(ads);
+  } catch (error) {
+    console.error('Error fetching ads:', error);
+  }
+})();
+```
+
+#### Per Request Configuration
+
+You can also pass additional fetch options for individual requests to customize headers or other request parameters:
+
+```ts
+import client from 'blocket.js';
+
+(async () => {
+  try {
+    const ads = await client.find(
+      { query: 'macbook air', limit: 10 },
+      { headers: { 'Custom-Header': 'customValue' } }
+    );
+    console.log(ads);
+  } catch (error) {
+    console.error('Error fetching ads:', error);
+  }
+})();
+```
+
+## API Reference
+
+`client.find(query: BlocketQueryParams, fetchOptions?: FetchOptions): Promise<BlocketAd[]>`
+
+Searches for ads on Blocket based on the provided query parameters.
+
+- Parameters:
+  - `query`: An object conforming to the `BlocketQueryParams` interface:
+    - `query` (string): The search query (e.g., `'macbook air'`).
+    - `limit` (number, optional): Maximum number of results to return (default: 60).
+    - `sort` (string, optional): Sorting order (default: `'rel'`).
+    - `listingType` (string, optional): Listing type; `'s'` for selling, `'b'` for buying (default: `'s'`).
+    - `status` (string, optional): Ad status (`'active'` or `'inactive'`, default: `'active'`).
+    - `gl` (number, optional): Maximum distance in kilometers.
+    - `include` (string, optional): Additional filters or fields to include (e.g., 'image,description').
+  - `fetchOptions` (optional): Additional options to pass to the underlying fetch request.
+- Returns: A promise that resolves to an array of `BlocketAd` objects.

package/dist/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure = void 0;
+const client = __importStar(require("./client"));
+const config_1 = require("./config");
+Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return config_1.configure; } });
+exports.default = client;
+//# sourceMappingURL=index.js.map

package/lib/client/index.ts

@@ -0,0 +1,63 @@
+import { apiRequest } from './request';
+import { getConfig } from '@/config';
+
+import type { FetchOptions } from 'ofetch';
+import type { BlocketQueryParams, BlocketAd, BlocketResponse } from '@/types';
+
+/**
+ * Remap BlocketQueryParams to API query parameters.
+ * @param params Blocket query parameters.
+ * @returns Remapped query parameters.
+ */
+function remapQueryParams(params: BlocketQueryParams): Record<string, any> {
+  return {
+    q: params.query,
+    lim: params.limit,
+    sort: params.sort,
+    st: params.listingType,
+    status: params.status,
+    gl: params.gl,
+    include: params.include,
+  };
+}
+
+/**
+ * Find ads on Blocket based on query parameters.
+ * @param query Blocket query parameters.
+ * @param fetchOptions Additional fetch options.
+ * @returns Array of Blocket ads.
+ */
+export async function find(
+  query: BlocketQueryParams,
+  fetchOptions?: FetchOptions<'json', any>
+): Promise<BlocketAd[]> {
+  const config = getConfig();
+  const response = await apiRequest<BlocketResponse>(config.apiBaseUrl, {
+    query: remapQueryParams(query),
+    ...fetchOptions,
+  });
+
+  if (!response || !response.data || !Array.isArray(response.data)) {
+    throw new Error(
+      `Unexpected Blocket API response structure, expected array of ads, got: ${typeof response?.data}`
+    );
+  }
+
+  return response.data;
+}
+
+/**
+ * Get details of a specific ad by its ID.
+ * @param adId Advertisement ID.
+ * @param fetchOptions Additional fetch options.
+ * @returns Blocket ad details.
+ */
+export async function getAd(
+  adId: string,
+  fetchOptions?: FetchOptions<'json', any>
+): Promise<BlocketAd> {
+  const config = getConfig();
+  const url = `${config.apiBaseUrl}/ad/${adId}`;
+
+  return await apiRequest<BlocketAd>(url, fetchOptions);
+}

package/lib/client/request.ts

@@ -0,0 +1,43 @@
+import { ofetch, type FetchOptions } from 'ofetch';
+
+import { fetchToken, setCachedToken } from './token';
+import { getConfig, logger } from '@/config';
+
+/**
+ * Make an API request with automatic token handling and retry on 401 errors.
+ * @param url URL to fetch.
+ * @param options Fetch options.
+ * @param retryCount Current retry count.
+ * @returns Parsed response of type T.
+ */
+export async function apiRequest<T>(
+  url: string,
+  options: FetchOptions<'json', any> = {},
+  retryCount: number = 0
+): Promise<T> {
+  const config = getConfig();
+  const token = await fetchToken();
+
+  try {
+    return await ofetch<T>(url, {
+      ...options,
+      headers: {
+        ...options.headers,
+        Authorization: `Bearer ${token}`,
+      },
+    });
+  } catch (error: any) {
+    if (error?.data?.status_code === 401 && retryCount < config.retryAttempts) {
+      logger(
+        'info',
+        `Token expired. Retrying request (${retryCount + 1}/${
+          config.retryAttempts
+        }).`
+      );
+      const newToken = await fetchToken(true);
+      setCachedToken(newToken);
+      return apiRequest<T>(url, options, retryCount + 1);
+    }
+    throw error;
+  }
+}

package/lib/client/token.ts

@@ -0,0 +1,43 @@
+import { ofetch } from 'ofetch';
+import { getConfig, logger } from '@/config';
+
+import type { BlocketAccessToken } from '@/types';
+
+let cachedToken: string | null = null;
+
+/**
+ * Get the cached token.
+ * @returns Cached bearer token if available.
+ */
+export const getCachedToken = (): string | null => cachedToken;
+
+/**
+ * Set the cached token.
+ * @param token Bearer token.
+ */
+export const setCachedToken = (token: string): void => {
+  cachedToken = token;
+};
+
+/**
+ * Fetch a new token from Blocket API.
+ * @param forceRefresh If true, ignores cached token and fetches a new one.
+ * @returns The bearer token.
+ */
+export const fetchToken = async (
+  forceRefresh: boolean = false
+): Promise<string> => {
+  if (!forceRefresh && cachedToken) return cachedToken;
+
+  logger('debug', 'Fetching new Blocket API token.');
+
+  const config = getConfig();
+
+  const tokenData = await ofetch<BlocketAccessToken>(config.tokenEndpoint);
+  if (!tokenData || !tokenData.bearerToken) {
+    throw new Error('Failed to retrieve Blocket API token.');
+  }
+
+  cachedToken = tokenData.bearerToken;
+  return cachedToken;
+};

package/lib/config/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Configuration interface.
+ */
+export interface BlocketConfig {
+  /**
+   * Base URL for the Blocket API.
+   * @default 'https://api.blocket.se/v1'
+   */
+  apiBaseUrl: string;
+  /**
+   * Endpoint URL to fetch the token.
+   * @default 'https://www.blocket.se/api/adout-api-route/refresh-token-and-validate-session'
+   */
+  tokenEndpoint: string;
+  /**
+   * Log level for debugging.
+   * Options: 'none', 'error', 'info', 'debug'
+   * @default 'error'
+   */
+  logLevel: 'none' | 'error' | 'info' | 'debug';
+  /**
+   * Maximum number of retry attempts on 401 error.
+   * @default 3
+   */
+  retryAttempts: number;
+}
+
+/**
+ * Default configuration.
+ */
+export const defaultConfig: BlocketConfig = {
+  apiBaseUrl: 'https://api.blocket.se/v1',
+  tokenEndpoint:
+    'https://www.blocket.se/api/adout-api-route/refresh-token-and-validate-session',
+  logLevel: 'error',
+  retryAttempts: 3,
+};
+
+let currentConfig: BlocketConfig = { ...defaultConfig };
+
+/**
+ * Configure Blocket.js globally.
+ * @param config Partial configuration to override defaults.
+ */
+export const configure = (config: Partial<BlocketConfig>): void => {
+  currentConfig = { ...currentConfig, ...config };
+};
+
+/**
+ * Get the current configuration.
+ * @returns The current Blocket.js configuration.
+ */
+export const getConfig = (): BlocketConfig => currentConfig;
+
+/**
+ * Simple logger function based on log level.
+ * @param level Log level of the message.
+ * @param message Message to log.
+ */
+export const logger = (
+  level: 'error' | 'info' | 'debug',
+  message: string
+): void => {
+  const levels = { none: 0, error: 1, info: 2, debug: 3 };
+  if (levels[getConfig().logLevel] >= levels[level]) {
+    console[level === 'error' ? 'error' : 'log'](message);
+  }
+};

package/lib/index.ts

@@ -0,0 +1,5 @@
+import * as client from './client';
+import { configure } from './config';
+
+export { configure };
+export default client;

package/lib/types/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Access token.
+ */
+export type BlocketAccessToken = {
+  user: null;
+  isLoggedIn: false;
+  bearerToken: string;
+};
+
+/**
+ * Blocket API response containing an array of ads.
+ */
+export interface BlocketResponse {
+  data: BlocketAd[];
+}
+
+/**
+ * Blocket advertisement object.
+ */
+export interface BlocketAd {
+  ad_id: string;
+  ad_status: 'active' | 'inactive' | string;
+  advertiser: {
+    account_id: string;
+    contact_methods: Record<string, any>;
+    name: string;
+    public_profile: Record<string, any>;
+    type: 'private' | 'business';
+  };
+  body: string;
+  category: Record<string, any>[];
+  co2_text: string;
+  images: Record<string, any>[];
+  list_id: string;
+  list_time: string; // ISO date string
+  location: Record<string, any>[];
+  map_url: string;
+  parameter_groups: Record<string, any>[];
+  parameters_raw: {
+    is_shipping_buy_now_enabled: Record<string, any>;
+    shipping_enabled: Record<string, any>;
+  };
+  price: {
+    suffix: string;
+    value: number;
+  };
+  price_badge?: {
+    icon: Record<string, any>;
+    id: string;
+    label: string;
+  };
+  share_url: string;
+  state_id: string;
+  subject: string;
+  type: string;
+  zipcode: string;
+}
+
+/**
+ * Parameters for querying Blocket ads.
+ */
+export interface BlocketQueryParams {
+  /**
+   * The search query.
+   * @example 'macbook air'
+   */
+  query: string;
+  /**
+   * The maximum number of results to return.
+   * @example 10
+   * @default 60
+   */
+  limit?: number;
+  /**
+   * The sorting order of the results.
+   * @example 'rel'
+   * @default 'rel'
+   */
+  sort?: 'rel';
+  /**
+   * The type of listing to search for. 's' for selling, 'b' for buying.
+   * @example 's'
+   * @default 's'
+   * @options 's' | 'b'
+   */
+  listingType?: 's' | 'b';
+  /**
+   * The status of the ad.
+   * @example 'active'
+   * @default 'active'
+   */
+  status?: 'active' | 'inactive' | string;
+  /**
+   * The maximum distance in kilometers from the search location.
+   * @example 10
+   */
+  gl?: number;
+  /**
+   * Additional filters or fields to include in the response.
+   * @example 'image,description'
+   */
+  include?: string;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "blocket.js",
+  "version": "1.0.0",
+  "description": "A user-friendly js wrapper for blocket.se",
+  "keywords": [
+    "blocket",
+    "javascript",
+    "api",
+    "wrapper",
+    "blocket.js"
+  ],
+  "license": "MIT",
+  "author": "Philip Rutberg <philiprutberg00@gmail.com> (https://philiprutberg.com/)",
+  "homepage": "https://github.com/rutbergphilip/blocket.js#readme",
+  "main": "dist/index.js",
+  "directories": {
+    "lib": "lib"
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rutbergphilip/blocket.js.git"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test yet\" && exit 1",
+    "build": "tsc"
+  },
+  "bugs": {
+    "url": "https://github.com/rutbergphilip/blocket.js/issues"
+  },
+  "pre-push": [
+    "build"
+  ],
+  "dependencies": {
+    "ofetch": "^1.4.1"
+  },
+  "devDependencies": {
+    "pre-push": "^0.1.4",
+    "typescript": "^5.7.3"
+  }
+}