feeef 0.8.3 → 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];
       }
@@ -318,6 +323,65 @@ var ProductRepository = class extends ModelRepository {
   }
 };
 
+// src/feeef/repositories/store_invites_repository.ts
+var StoreInvitesRepository = class {
+  constructor(client, resource) {
+    this.client = client;
+    this.resource = resource;
+  }
+  /**
+   * Lists invites for a store.
+   * @param storeId - The store ID.
+   * @param params - Optional filters (e.g. status).
+   * @returns A Promise that resolves to the list of invites.
+   */
+  async list(storeId, params) {
+    const res = await this.client.get(`/${this.resource}/${storeId}/invites`, { params });
+    return res.data;
+  }
+  /**
+   * Creates a store invite (sends email to invitee).
+   * @param storeId - The store ID.
+   * @param data - The invite data.
+   * @returns A Promise that resolves to the created invite.
+   */
+  async create(storeId, data) {
+    const res = await this.client.post(`/${this.resource}/${storeId}/invites`, data);
+    return res.data;
+  }
+  /**
+   * Gets invite details (public or full if authorized).
+   * @param storeId - The store ID.
+   * @param inviteId - The invite ID.
+   * @returns A Promise that resolves to the invite.
+   */
+  async get(storeId, inviteId) {
+    const res = await this.client.get(`/${this.resource}/${storeId}/invites/${inviteId}`);
+    return res.data;
+  }
+  /**
+   * Revokes a pending invite.
+   * @param storeId - The store ID.
+   * @param inviteId - The invite ID.
+   */
+  async revoke(storeId, inviteId) {
+    await this.client.delete(`/${this.resource}/${storeId}/invites/${inviteId}`);
+  }
+  /**
+   * Accepts an invite (authenticated user's email must match invite email).
+   * @param storeId - The store ID.
+   * @param inviteId - The invite ID.
+   * @param token - The invite token from the email link.
+   * @returns A Promise that resolves to the created store member.
+   */
+  async accept(storeId, inviteId, token) {
+    const res = await this.client.post(`/${this.resource}/${storeId}/invites/${inviteId}/accept`, {
+      token
+    });
+    return res.data;
+  }
+};
+
 // src/feeef/repositories/stores.ts
 var StoreRepository = class extends ModelRepository {
   /**
@@ -410,67 +474,24 @@ var StoreRepository = class extends ModelRepository {
     await this.client.delete(`/${this.resource}/${storeId}/members/${memberId}`);
   }
   /**
-   * Creates a store invite (sends email to invitee).
-   * @param storeId - The store ID.
-   * @param data - The invite data.
-   * @returns A Promise that resolves to the created invite.
-   */
-  async createInvite(storeId, data) {
-    const res = await this.client.post(`/${this.resource}/${storeId}/invites`, data);
-    return res.data;
-  }
-  /**
-   * Lists invites for a store.
-   * @param storeId - The store ID.
-   * @param params - Optional filters (e.g. status).
-   * @returns A Promise that resolves to the list of invites.
-   */
-  async listInvites(storeId, params) {
-    const res = await this.client.get(`/${this.resource}/${storeId}/invites`, { params });
-    return res.data;
-  }
-  /**
-   * Revokes a pending invite.
-   * @param storeId - The store ID.
-   * @param inviteId - The invite ID.
-   */
-  async revokeInvite(storeId, inviteId) {
-    await this.client.delete(`/${this.resource}/${storeId}/invites/${inviteId}`);
-  }
-  /**
-   * Gets invite details (public or full if authorized).
-   * @param storeId - The store ID.
-   * @param inviteId - The invite ID.
-   * @returns A Promise that resolves to the invite.
+   * Repository for store invites. Use e.g. `ff.stores.invites.list(storeId)`, `ff.stores.invites.create(storeId, data)`.
    */
-  async getInvite(storeId, inviteId) {
-    const res = await this.client.get(`/${this.resource}/${storeId}/invites/${inviteId}`);
-    return res.data;
-  }
-  /**
-   * Accepts an invite (authenticated user's email must match invite email).
-   * @param storeId - The store ID.
-   * @param inviteId - The invite ID.
-   * @param token - The invite token from the email link.
-   * @returns A Promise that resolves to the created store member.
-   */
-  async acceptInvite(storeId, inviteId, token) {
-    const res = await this.client.post(`/${this.resource}/${storeId}/invites/${inviteId}/accept`, {
-      token
-    });
-    return res.data;
+  get invites() {
+    return new StoreInvitesRepository(this.client, this.resource);
   }
   /**
    * Upgrades or renews a store's subscription plan.
    * @param id - The store ID.
    * @param plan - The plan type to upgrade to.
    * @param months - The number of months (1-12).
-   * @returns A Promise that resolves when the upgrade is complete.
+   * @param code - Optional promo code.
    */
-  async upgrade(id, plan, months) {
+  async upgrade(id, plan, months, options) {
     await this.client.post(`/${this.resource}/${id}/subscription/upgrade`, {
       plan,
-      months
+      months,
+      // eslint-disable-next-line eqeqeq
+      ...options?.code != null && options.code !== "" && { code: options.code }
     });
   }
   /**
@@ -796,6 +817,22 @@ var AppRepository = class extends ModelRepository {
   constructor(client) {
     super("apps", client);
   }
+  /**
+   * Lists apps with optional pagination and filterator.
+   * @param options - Page, limit, filterator, q, and extra params forwarded to the API.
+   */
+  async list(options) {
+    const params = { ...options?.params };
+    if (options) {
+      if (options.page !== void 0) params.page = options.page;
+      if (options.limit !== void 0) params.limit = options.limit;
+      if (options.q !== void 0) params.q = options.q;
+      if (options.filterator !== void 0) params.filterator = options.filterator;
+      if (options.userId !== void 0) params.userId = options.userId;
+      if (options.active !== void 0) params.active = options.active;
+    }
+    return super.list({ page: options?.page, limit: options?.limit, params });
+  }
   /**
    * Regenerates the client secret for the app. Returns the app with
    * clientSecret set once; store it securely.
@@ -809,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).
@@ -837,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 {
   /**
@@ -972,6 +1090,49 @@ var DepositRepository = class extends ModelRepository {
   }
 };
 
+// src/feeef/repositories/promos.ts
+var PromoRepository = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Lists promos with optional pagination and validNow filter.
+   */
+  async list(params) {
+    const query = {};
+    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.
+   */
+  async validate(params) {
+    const res = await this.client.post("/promos/validate", {
+      code: params.code,
+      storeId: params.storeId
+    });
+    return res.data;
+  }
+  /**
+   * Creates a promo (admin). Returns the created promo.
+   */
+  async create(data) {
+    const res = await this.client.post("/promos", data);
+    return res.data;
+  }
+};
+
 // src/feeef/repositories/transfers.ts
 var TransferRepository = class extends ModelRepository {
   /**
@@ -3446,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.
    */
@@ -3458,6 +3623,10 @@ var FeeeF = class {
    * The repository for managing transfers.
    */
   transfers;
+  /**
+   * The repository for managing promo codes (list, validate, create).
+   */
+  promos;
   /**
    * The repository for managing categories.
    */
@@ -3533,9 +3702,11 @@ 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);
+    this.promos = new PromoRepository(this.client);
     this.categories = new CategoryRepository(this.client);
     this.countries = new CountryRepository(this.client);
     this.states = new StateRepository(this.client);
@@ -3995,6 +4166,7 @@ export {
   ModelRepository,
   NoestDeliveryIntegrationApi,
   NotificationsService,
+  OAuthRepository,
   OrderRepository,
   OrderStatus,
   PaymentStatus,
@@ -4004,6 +4176,7 @@ export {
   ProductStatus,
   ProductType,
   ProductVariantView,
+  PromoRepository,
   ShippingMethodPolicy,
   ShippingMethodRepository,
   ShippingMethodStatus,
@@ -4014,6 +4187,7 @@ export {
   StorageService,
   StoreActionType,
   StoreInviteStatus,
+  StoreInvitesRepository,
   StoreMemberRole,
   StoreRepository,
   StoreSubscriptionStatus,