feeef 0.8.4 → 0.8.5

package/README.md

@@ -213,3 +213,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,14 @@ 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).
+   *
+   * 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).
@@ -869,6 +882,79 @@ var AppRepository = class extends ModelRepository {
   }
 };
 
+// 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
 var DepositRepository = class extends ModelRepository {
   /**
@@ -1017,9 +1103,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 +3607,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 +3702,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);
@@ -4067,6 +4166,7 @@ export {
   ModelRepository,
   NoestDeliveryIntegrationApi,
   NotificationsService,
+  OAuthRepository,
   OrderRepository,
   OrderStatus,
   PaymentStatus,