feeef 0.8.4 → 0.8.9

package/README.md

@@ -2,6 +2,14 @@
 
 `feeefjs` is a TypeScript library for managing feeef e-commerce platforms for self-hosted stores. It provides a wrapper for feeef rest api such like send order..., also have frontend srvices like the `CartService` class for managing cart items, shipping methods, and calculating totals. The library also includes a `NotifiableService` base class for handling listeners that react to changes in the service state.
 
+## Developer OAuth (third-party apps)
+
+Use `OAuthRepository.buildAuthorizeUrl` (point `baseUrl` at the **accounts** host, e.g. `https://accounts.feeef.org`) and `FeeeF` client `oauth.exchangeAuthorizationCode` / `revokeToken` / `introspectToken` against the **API** base (`.../v1`). Full flow, scopes, and troubleshooting: Feeef backend **`docs/OAUTH2_DEVELOPER.md`** (in the Adonis API repo).
+
+## Realtime (AdonisJS Transmit)
+
+Server-Sent Events use the same **API origin** as the REST client, but **without** the `/v1` or `/api/v1` prefix (e.g. `https://api.feeef.org/__transmit/events`). Use `createFeeefTransmit({ apiBaseUrl, getAccessToken })` so subscribe/unsubscribe POSTs get a proper `Authorization: Bearer …` header. The underlying client is the official [`@adonisjs/transmit-client`](https://www.npmjs.com/package/@adonisjs/transmit-client) (`Transmit`, `Subscription` are re-exported).
+
 ---
 
 # CartService & NotifiableService
@@ -213,3 +221,76 @@ interface ProductOffer {
 ## Contributing
 
 Feel free to fork this repository and contribute improvements, bug fixes, or additional features. Open a pull request for any major changes!
+
+## Developer OAuth (Authorization Code)
+
+Use this flow when a third-party app (created in `apps`) needs user authorization.
+
+### Endpoints
+
+- Authorize: `GET /v1/oauth/authorize`
+- Token: `POST /v1/oauth/token`
+- Revoke: `POST /v1/oauth/revoke`
+- Introspect: `POST /v1/oauth/introspect`
+
+### Step-by-step (Google-like)
+
+1. Build authorize URL:
+
+```ts
+import { FeeeF, OAuthRepository } from 'feeef'
+
+const feeef = new FeeeF({
+  apiKey: '<your_api_key>',
+  baseURL: 'https://api.feeef.org/v1',
+})
+
+const authorizeUrl = OAuthRepository.buildAuthorizeUrl({
+  baseUrl: 'https://api.feeef.org/v1',
+  clientId: '<client_id>',
+  redirectUri: 'https://your-app.com/oauth/callback',
+  scope: ['*'], // or explicit scopes
+  state: crypto.randomUUID(),
+})
+```
+
+2. Open `authorizeUrl` in browser.
+3. If user is not signed in, API may return `401` with:
+   - `error: "login_required"`
+   - `login_url` (accounts sign-in URL with `next`)
+4. Redirect user to `login_url`.
+5. After sign-in + authorization, user is redirected to your callback with `code` (and `state`).
+6. Exchange `code` for token:
+
+```ts
+const tokenResponse = await feeef.oauth.exchangeAuthorizationCode({
+  code: '<code_from_callback>',
+  redirectUri: 'https://your-app.com/oauth/callback',
+  clientId: '<client_id>',
+  clientSecret: '<client_secret>',
+})
+
+await feeef.oauth.revokeToken(tokenResponse.access_token)
+
+const introspection = await feeef.oauth.introspectToken(tokenResponse.access_token)
+console.log(introspection.active)
+```
+
+Alternative static helper:
+
+```ts
+import { OAuthRepository } from 'feeef'
+
+const authorizeUrl = OAuthRepository.buildAuthorizeUrl({
+  baseUrl: 'https://api.feeef.org/v1',
+  clientId: '<client_id>',
+  redirectUri: 'https://your-app.com/oauth/callback',
+})
+```
+
+### Important
+
+- `redirect_uri` must exactly match one of the app's registered redirect URIs.
+- Keep `client_secret` server-side only.
+- Always validate `state` on callback.
+- Prefer PKCE (`code_challenge`, `code_verifier`) for public clients.

package/build/index.js

@@ -141,7 +141,12 @@ var OrderRepository = class extends ModelRepository {
       if (options.page) params.page = options.page;
       if (options.offset) params.offset = options.offset;
       if (options.limit) params.limit = options.limit;
-      if (options.storeId) params.store_id = options.storeId;
+      const useMultiStore = options.storeIds != null && options.storeIds.length > 0;
+      if (useMultiStore) {
+        params.store_ids = options.storeIds;
+      } else if (options.storeId) {
+        params.store_id = options.storeId;
+      }
       if (options.status) {
         params.status = Array.isArray(options.status) ? options.status : [options.status];
       }
@@ -841,6 +846,17 @@ var AppRepository = class extends ModelRepository {
   }
   /**
    * Builds the OAuth authorize URL to which the user should be redirected.
+   * This is the first step of the authorization-code flow (similar UX to Google OAuth).
+   *
+   * Production: opening this URL on the **API** host (`api.*`) issues a redirect to the same path on
+   * **accounts.*** so the consent screen appears on the trusted accounts domain; query params are preserved.
+   *
+   * If the user is not logged in yet, API `GET /oauth/authorize` returns:
+   * - `401 login_required`
+   * - `login_url` (accounts sign-in URL with `next=...`)
+   *
+   * The client should navigate to `login_url`, let the user sign in, and then
+   * continue by opening the original authorize URL again (or rely on `next`).
    *
    * @param params - Parameters for the authorize URL.
    * @param params.baseUrl - API base URL (e.g. https://api.feeef.org/api/v1).
@@ -867,6 +883,120 @@ var AppRepository = class extends ModelRepository {
     }
     return url.toString();
   }
+  /**
+   * Public `apps.public_data` (no auth). Pass [config] to skip Authorization if your axios instance adds it globally.
+   */
+  async getPublicData(id, config) {
+    const res = await this.client.get(`/${this.resource}/${id}/public-data`, config);
+    return res.data;
+  }
+  async getPrivateData(id) {
+    const res = await this.client.get(`/${this.resource}/${id}/private-data`);
+    return res.data;
+  }
+  async putPublicData(id, publicNamespaces) {
+    const res = await this.client.put(`/${this.resource}/${id}/public-data`, {
+      public: publicNamespaces
+    });
+    return res.data;
+  }
+  async putPrivateData(id, privateNamespaces) {
+    const res = await this.client.put(`/${this.resource}/${id}/private-data`, {
+      private: privateNamespaces
+    });
+    return res.data;
+  }
+  async getUserDataMe(id) {
+    const res = await this.client.get(`/${this.resource}/${id}/user-data/me`);
+    return res.data;
+  }
+  async putUserDataMe(id, publicNamespaces) {
+    const res = await this.client.put(`/${this.resource}/${id}/user-data/me`, {
+      public: publicNamespaces
+    });
+    return res.data;
+  }
+  async getUserDataForUser(appId, userId) {
+    const res = await this.client.get(`/${this.resource}/${appId}/user-data/users/${userId}`);
+    return res.data;
+  }
+  async putUserDataForUser(appId, userId, body) {
+    const res = await this.client.put(`/${this.resource}/${appId}/user-data/users/${userId}`, body);
+    return res.data;
+  }
+};
+
+// src/feeef/repositories/oauth.ts
+var OAuthRepository = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Builds the authorize URL for browser redirect.
+   */
+  static buildAuthorizeUrl(params) {
+    const base = params.baseUrl.endsWith("/") ? params.baseUrl : `${params.baseUrl}/`;
+    const url = new URL("oauth/authorize", base);
+    url.searchParams.set("client_id", params.clientId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("response_type", "code");
+    if (params.scope?.length) url.searchParams.set("scope", params.scope.join(" "));
+    if (params.state) url.searchParams.set("state", params.state);
+    if (params.codeChallenge) url.searchParams.set("code_challenge", params.codeChallenge);
+    if (params.codeChallengeMethod) {
+      url.searchParams.set("code_challenge_method", params.codeChallengeMethod);
+    }
+    return url.toString();
+  }
+  /**
+   * Exchanges an authorization code for an access token.
+   */
+  async exchangeAuthorizationCode(params) {
+    const body = new URLSearchParams({
+      grant_type: "authorization_code",
+      code: params.code,
+      redirect_uri: params.redirectUri,
+      client_id: params.clientId,
+      client_secret: params.clientSecret
+    });
+    if (params.codeVerifier) {
+      body.set("code_verifier", params.codeVerifier);
+    }
+    const response = await this.client.post("/oauth/token", body.toString(), {
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Revokes an OAuth token.
+   */
+  async revokeToken(token, tokenTypeHint) {
+    const body = new URLSearchParams({ token });
+    if (tokenTypeHint) {
+      body.set("token_type_hint", tokenTypeHint);
+    }
+    const response = await this.client.post("/oauth/revoke", body.toString(), {
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      }
+    });
+    return response.data;
+  }
+  /**
+   * Introspects an OAuth token.
+   */
+  async introspectToken(token) {
+    const body = new URLSearchParams({ token });
+    const response = await this.client.post("/oauth/introspect", body.toString(), {
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      }
+    });
+    return response.data;
+  }
 };
 
 // src/feeef/repositories/deposits.ts
@@ -1017,9 +1147,17 @@ var PromoRepository = class {
     if (params?.page != null) query.page = params.page;
     if (params?.limit != null) query.limit = params.limit;
     if (params?.validNow === true) query.validNow = "1";
+    if (params?.filterator) query.filterator = params.filterator;
     const res = await this.client.get("/promos", { params: query });
     return res.data;
   }
+  /**
+   * Fetches a single promo by id.
+   */
+  async find(params) {
+    const res = await this.client.get(`/promos/${params.id}`);
+    return res.data;
+  }
   /**
    * Validates a promo code. Returns validation result with discount info or reason.
    */
@@ -3513,6 +3651,10 @@ var FeeeF = class {
    * The repository for managing developer-registered apps (OAuth clients).
    */
   apps;
+  /**
+   * The repository for OAuth2 authorize/token/revoke/introspect operations.
+   */
+  oauth;
   /**
    * The repository for managing orders.
    */
@@ -3604,6 +3746,7 @@ var FeeeF = class {
     this.imageGenerations = new ImageGenerationsRepository(this.client);
     this.users = new UserRepository(this.client);
     this.apps = new AppRepository(this.client);
+    this.oauth = new OAuthRepository(this.client);
     this.orders = new OrderRepository(this.client);
     this.deposits = new DepositRepository(this.client);
     this.transfers = new TransferRepository(this.client);
@@ -3957,6 +4100,77 @@ var EmbaddedContactType = /* @__PURE__ */ ((EmbaddedContactType2) => {
   return EmbaddedContactType2;
 })(EmbaddedContactType || {});
 
+// src/realtime/transmit.ts
+import { Transmit } from "@adonisjs/transmit-client";
+import { Subscription, Transmit as Transmit2 } from "@adonisjs/transmit-client";
+function transmitRootFromApiBaseUrl(apiBaseUrl) {
+  let u = apiBaseUrl.trim().replace(/\/+$/, "");
+  if (u.endsWith("/api/v1")) {
+    u = u.slice(0, -"/api/v1".length);
+  } else if (u.endsWith("/v1")) {
+    u = u.slice(0, -"/v1".length);
+  }
+  return u;
+}
+function retrieveXsrfTokenFromCookie() {
+  const cookie = globalThis.document?.cookie;
+  if (!cookie) return null;
+  const match = cookie.match(new RegExp("(^|;\\s*)(XSRF-TOKEN)=([^;]*)"));
+  return match ? decodeURIComponent(match[3]) : null;
+}
+var FeeefTransmitHttpClient = class {
+  constructor(options, getAuthorizationHeader) {
+    this.options = options;
+    this.getAuthorizationHeader = getAuthorizationHeader;
+  }
+  send(request) {
+    return fetch(request);
+  }
+  createRequest(path, body) {
+    const headers = {
+      "Content-Type": "application/json",
+      "X-XSRF-TOKEN": retrieveXsrfTokenFromCookie() ?? ""
+    };
+    const auth = this.getAuthorizationHeader();
+    if (auth) {
+      headers.Authorization = auth.startsWith("Bearer ") ? auth : `Bearer ${auth}`;
+    }
+    return new Request(`${this.options.baseUrl}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ uid: this.options.uid, ...body }),
+      credentials: "include"
+    });
+  }
+};
+function createFeeefTransmit(options) {
+  const baseUrl = transmitRootFromApiBaseUrl(options.apiBaseUrl);
+  const getToken = options.getAccessToken ?? (() => void 0);
+  return new Transmit({
+    ...options.transmit,
+    baseUrl,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Transmit’s HttpClient is not exported; FeeefTransmitHttpClient matches its shape.
+    httpClientFactory: (url, uid) => new FeeefTransmitHttpClient({ baseUrl: url, uid }, () => {
+      const t = getToken();
+      if (t === null || t === void 0 || t === "") return void 0;
+      const s = String(t).trim();
+      return s.startsWith("Bearer ") ? s : `Bearer ${s}`;
+    })
+  });
+}
+function createFeeefTransmitFromAxios(client, options) {
+  const apiBaseUrl = client.defaults.baseURL ?? "";
+  return createFeeefTransmit({
+    ...options,
+    apiBaseUrl,
+    getAccessToken: () => {
+      const raw = client.defaults.headers.common?.Authorization;
+      if (typeof raw !== "string") return void 0;
+      return raw.replace(/^Bearer\s+/i, "").trim() || void 0;
+    }
+  });
+}
+
 // src/utils.ts
 var convertDartColorToCssNumber = (dartColor) => {
   const alpha = dartColor >> 24 & 255;
@@ -4059,6 +4273,7 @@ export {
   FeedbackRepository,
   FeedbackStatus,
   FeeeF,
+  FeeefTransmitHttpClient,
   GoogleSheetIntegrationApi,
   ImageGenerationsRepository,
   ImagePromptTemplatesRepository,
@@ -4067,6 +4282,7 @@ export {
   ModelRepository,
   NoestDeliveryIntegrationApi,
   NotificationsService,
+  OAuthRepository,
   OrderRepository,
   OrderStatus,
   PaymentStatus,
@@ -4092,8 +4308,10 @@ export {
   StoreRepository,
   StoreSubscriptionStatus,
   StoreSubscriptionType,
+  Subscription,
   TiktokPixelEvent,
   TransferRepository,
+  Transmit2 as Transmit,
   UserRepository,
   VariantOptionType,
   WebhookEvent,
@@ -4102,6 +4320,8 @@ export {
   ZimouDeliveryIntegrationApi,
   convertDartColorToCssNumber,
   convertOrderEntityToOrderTrackEntity,
+  createFeeefTransmit,
+  createFeeefTransmitFromAxios,
   createImageGenerationFormData,
   cssColorToHslString,
   dartColorToCssColor,
@@ -4137,6 +4357,7 @@ export {
   serializeAttachmentPayloads,
   serializeImagePromptTemplateCreate,
   serializeImagePromptTemplateUpdate,
+  transmitRootFromApiBaseUrl,
   tryFixPhoneNumber,
   validatePhoneNumber
 };