freelancer-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MURTESA
+
+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/examples/SearchProject.js

@@ -0,0 +1,28 @@
+const { SearchProjects } = require("../src/index");
+
+const projects = new SearchProjects({
+  accessToken: "access_token",
+  sandbox: true,
+});
+
+(async () => {
+  try {
+    const result = await projects.search({
+      query: "software",
+      project_types: ["fixed"],
+      min_price: 50,
+      max_price: 1000,
+      jobs: [1, 2, 3], // job id
+      languages: ["en"],
+      project_statuses: ["active"],
+      sort_field: "time_updated",
+      limit: 10,
+      full_description: true,
+      user_details: true,
+    });
+
+    console.log(result.result.projects);
+  } catch (err) {
+    console.error("Error:", err.details || err.message);
+  }
+})();

package/examples/auth_link.js

@@ -0,0 +1,31 @@
+const { FreelancerAuth } = require("../src/index");
+
+(async () => {
+  const clientId = "app_id";
+  const clientSecret = "client_secret";
+  const redirectUri = "https://example.com/callback";
+  const sandbox = true;
+
+  const flags = {
+    messaging: true,        
+    project_create: true,    
+    project_manage: false,   
+    contest_create: false,   
+    contest_manage: false,   
+    user_information: true,  
+    location_tracking_create: false, 
+    location_tracking_view: false,   
+  };
+
+  const auth = new FreelancerAuth({ clientId, clientSecret, redirectUri, sandbox, flags });
+
+  const authUrl = auth.generateAuthLink();
+  console.log("Open this link in your browser to authorize the app:");
+  console.log(authUrl);
+  const code = await FreelancerAuth.askCode("Enter the code you received: ");
+
+  const tokens = await auth.exchangeCode(code.trim());
+
+  console.log("Access Token:", tokens.access_token);
+  console.log("Refresh Token:", tokens.refresh_token);
+})();

package/examples/check_token.js

@@ -0,0 +1,15 @@
+const { TOKEN } = require("../src/index");
+
+const client = new TOKEN({
+  token: "access_token",
+  sandbox: true,
+});
+
+(async () => {
+  try {
+    const valid = await client.validateToken();
+    console.log("Token valid?", valid);
+  } catch (err) {
+    console.error("Error validating token:", err.message);
+  }
+})();

package/examples/refresh_token.js

@@ -0,0 +1,20 @@
+const { FreelancerAuth } = require("../src");
+
+(async () => {
+  try {
+    const auth = new FreelancerAuth({
+      clientId: "app_id",
+      clientSecret: "client_secret",
+      sandbox: true,
+    });
+
+    auth.refreshToken = "refresh_token";
+
+    const tokens = await auth.refreshTokenRequest();
+
+    console.log("New Access Token:", tokens.access_token);
+    console.log("New Refresh Token:", tokens.refresh_token);
+  } catch (err) {
+    console.error("Failed to refresh token:", err.message);
+  }
+})();

package/examples/selfprofile.js

@@ -0,0 +1,19 @@
+const { SelfProfile } = require("../src/index");
+(async () => {
+  try {
+    const profile = new SelfProfile({
+      accessToken: "access_token",
+      sandbox: true
+    });
+
+    const res = await profile.getMyProfile({
+      avatar: true,
+      display_info: true,
+      profile_description: true,
+    });
+
+    console.log(res);
+  } catch (err) {
+    console.error("Error:", err.message);
+  }
+})();

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "freelancer-kit",
+  "version": "1.0.0",
+  "description": "Unofficial Node.js toolkit for integrating with the Freelancer.com API",
+  "author": "MURTESA",
+  "license": "MIT",
+  "main": "src/index.js",
+  "keywords": [
+    "freelancer",
+    "freelancer-kit",
+    "freelancer-api",
+    "nodejs",
+    "sdk",
+    "client",
+    "unofficial"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "dependencies": {
+    "node-fetch": "^2.7.0"
+  }
+}

package/src/classes/FreelancerAuth.js

@@ -0,0 +1,111 @@
+const fetch = require("node-fetch");
+const readline = require("readline");
+
+class FreelancerAuth {
+  constructor({ clientId, clientSecret, redirectUri = "http://localhost", sandbox = false, flags = {} }) {
+    if (!clientId || !clientSecret) throw new Error("clientId and clientSecret are required");
+
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.redirectUri = redirectUri;
+    this.sandbox = sandbox;
+    this.flags = flags;
+    this.token = null;
+    this.refreshToken = null;
+
+    this.oauthUrl = sandbox
+      ? "https://accounts.freelancer-sandbox.com/oauth"
+      : "https://accounts.freelancer.com/oauth";
+  }
+
+  generateAuthLink() {
+    const scopes = ["basic"];
+    if (this.flags.project_create) scopes.push("1");
+    if (this.flags.project_manage) scopes.push("2");
+    if (this.flags.contest_create) scopes.push("3");
+    if (this.flags.contest_manage) scopes.push("4");
+    if (this.flags.messaging) scopes.push("5");
+    if (this.flags.user_information) scopes.push("6");
+    if (this.flags.location_tracking_create) scopes.push("7");
+    if (this.flags.location_tracking_view) scopes.push("8");
+    
+    const scopeString = scopes.join(" ");
+    return `${this.oauthUrl}/authorise?response_type=code&client_id=${this.clientId}&redirect_uri=${encodeURIComponent(
+      this.redirectUri
+    )}&scope=${encodeURIComponent(scopeString)}`;
+  }
+
+  async exchangeCode(code) {
+    const url = `${this.oauthUrl}/token`;
+    const params = new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      code: code.trim(),
+      redirect_uri: this.redirectUri,
+    });
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: params.toString(),
+    });
+
+    const text = await res.text();
+    if (!res.ok) throw new Error(`Token request failed: ${res.status} ${res.statusText}\n${text}`);
+
+    const data = JSON.parse(text);
+    this.token = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return data;
+  }
+
+  async refreshTokenRequest() {
+    if (!this.refreshToken) throw new Error("No refresh token available");
+
+    const url = `${this.oauthUrl}/token`;
+    const params = new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      refresh_token: this.refreshToken,
+    });
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: params.toString(),
+    });
+
+    const text = await res.text();
+    if (!res.ok) throw new Error(`Refresh token request failed: ${res.status} ${res.statusText}\n${text}`);
+
+    const data = JSON.parse(text);
+    this.token = data.access_token;
+    this.refreshToken = data.refresh_token;
+    return data;
+  }
+
+  async request(endpoint, options = {}) {
+    if (!this.token) throw new Error("No access token, authenticate first");
+    const url = `https://www.freelancer.com/api${endpoint}`;
+    const res = await fetch(url, {
+      ...options,
+      headers: {
+        Authorization: "Bearer " + this.token,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...(options.headers || {}),
+      },
+    });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`API request failed: ${res.status} ${res.statusText}\n${text}`);
+    return JSON.parse(text);
+  }
+
+  static askCode(promptText = "Enter the code you received: ") {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => rl.question(promptText, (ans) => { rl.close(); resolve(ans); }));
+  }
+}
+module.exports = FreelancerAuth;

package/src/classes/SearchProjects.js

@@ -0,0 +1,52 @@
+const fetch = require("node-fetch");
+
+class SearchProjects {
+  constructor({ accessToken, sandbox = false }) {
+    if (!accessToken) {
+      throw new Error("accessToken is required");
+    }
+
+    this.accessToken = accessToken;
+    this.baseUrl = sandbox
+      ? "https://www.freelancer-sandbox.com/api/projects/0.1"
+      : "https://www.freelancer.com/api/projects/0.1";
+  }
+
+
+  async search(filters = {}) {
+    const url = new URL(`${this.baseUrl}/projects/all/`);
+
+    Object.entries(filters).forEach(([key, value]) => {
+      if (value === undefined || value === null) return;
+
+      if (Array.isArray(value)) {
+        value.forEach((v) => {
+          url.searchParams.append(`${key}[]`, v);
+        });
+      } else {
+        url.searchParams.append(key, value);
+      }
+    });
+
+    const res = await fetch(url.toString(), {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "freelancer-oauth-v1": this.accessToken,
+      },
+    });
+
+    const data = await res.json();
+
+    if (!res.ok) {
+      const error = new Error(data.message || "Freelancer API Error");
+      error.status = res.status;
+      error.details = data;
+      throw error;
+    }
+
+    return data;
+  }
+}
+
+module.exports = SearchProjects;

package/src/classes/SelfProfile.js

@@ -0,0 +1,89 @@
+const fetch = require("node-fetch");
+
+class SelfProfile {
+  constructor({ accessToken, sandbox = false }) {
+    if (!accessToken) {
+      throw new Error("accessToken is required");
+    }
+
+    this.accessToken = accessToken;
+    this.sandbox = sandbox;
+
+    this.baseUrl = sandbox
+      ? "https://www.freelancer-sandbox.com/api/users/0.1"
+      : "https://www.freelancer.com/api/users/0.1";
+  }
+
+  buildQuery(params = {}) {
+    const query = new URLSearchParams();
+
+    for (const [key, value] of Object.entries(params)) {
+      if (value === true) {
+        query.append(key, "true");
+      } else if (value !== false && value != null) {
+        query.append(key, String(value));
+      }
+    }
+
+    return query.toString();
+  }
+
+  async request(endpoint) {
+    const res = await fetch(this.baseUrl + endpoint, {
+      headers: {
+        Accept: "application/json",
+        "freelancer-oauth-v1": this.accessToken,
+      },
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      throw new Error(JSON.stringify(data, null, 2));
+    }
+
+    return data;
+  }
+
+  filterProfile(user, params) {
+    const result = {};
+
+    if (params.avatar === true) {
+      result.avatar = user.avatar_xlarge_cdn || user.avatar_xlarge;
+    }
+
+    if (params.display_info === true) {
+      result.display_name = user.display_name;
+      result.tagline = user.tagline;
+      result.location = user.location;
+    }
+
+    if (params.profile_description === true) {
+      result.profile_description = user.profile_description;
+    }
+
+    if (params.reputation === true) {
+      result.reputation = user.reputation;
+    }
+
+    if (params.cover_image === true) {
+      result.cover_image = user.cover_image;
+    }
+
+    return result;
+  }
+
+  async getMyProfile(params = {}) {
+    const query = this.buildQuery(params);
+    const endpoint = `/self/${query ? `?${query}` : ""}`;
+
+    const response = await this.request(endpoint);
+
+    if (!response || !response.result) {
+      throw new Error("Invalid API response");
+    }
+
+    return this.filterProfile(response.result, params);
+  }
+}
+
+module.exports = SelfProfile;

package/src/classes/Token.js

@@ -0,0 +1,40 @@
+const fetch = require("node-fetch");
+
+class Token {
+  constructor({ token, sandbox = false }) {
+    if (!token) throw new Error("Token is required");
+    this.token = token;
+    this.baseUrl = sandbox
+      ? "https://www.freelancer-sandbox.com/api"
+      : "https://www.freelancer.com/api";
+  }
+
+  async request(endpoint, options = {}) {
+    const url = this.baseUrl + endpoint;
+    const res = await fetch(url, {
+      ...options,
+      headers: {
+        Authorization: "Bearer " + this.token,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...(options.headers || {}),
+      },
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Freelancer API error: ${res.status} ${res.statusText}\n${text}`);
+    }
+    return res.json();
+  }
+
+  async validateToken() {
+    try {
+      await this.request("/users/0.1/self/");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+module.exports = Token;

package/src/index.js

@@ -0,0 +1,14 @@
+const SelfProfile = require("./classes/SelfProfile");
+const Token = require("./classes/Token");
+const SearchProjects = require("./classes/SearchProjects");
+const FreelancerAuth = require("./classes/FreelancerAuth");
+const Bid = require("./classes/Bid")
+
+
+module.exports = {
+  SelfProfile,
+  Token,
+  SearchProjects,
+  FreelancerAuth,
+  Bid,
+};