[merchant-api] Initial commit for garf-merchant-api

Author: AndreyMarkinPPC

libs/garf_community/google/merchant/README.md

@@ -0,0 +1,65 @@
+# `garf` for Merchant API
+
+[![PyPI](https://img.shields.io/pypi/v/garf-merchant-api?logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/garf-merchant-api)
+[![Downloads PyPI](https://img.shields.io/pypi/dw/garf-merchant-api?logo=pypi)](https://pypi.org/project/garf-merchant-api/)
+
+`garf-merchant-api` simplifies fetching data from Merchant API using SQL-like queries.
+
+## Prerequisites
+
+* [Merchant API](https://console.cloud.google.com/apis/library/merchantapi.googleapis.com) enabled.
+
+## Installation
+
+`pip install garf-merchant-api`
+
+## Usage
+
+### Run as a library
+```
+from garf_merchant_api import report_fetcher
+from garf_io import writer
+
+
+# Specify query
+query = """
+  SELECT
+    date,
+    clicks
+    FROM product_performance_view
+    WHERE date BETWEEN '2023-12-01' AND '2023-12-03'
+  ORDER BY clicks DESC
+""
+
+# Fetch report
+fetched_report = (
+  report_fetcher.MerchantApiReportFetcher()
+  .fetch(query, query="<YOUR_SEARCH_QUERY_HERE">, account=ACCOUNT_ID)
+)
+
+# Write report to console
+console_writer = writer.create_writer('console')
+console_writer.write(fetched_report, 'output')
+```
+
+### Run via CLI
+
+> Install `garf-executors` package to run queries via CLI (`pip install garf-executors`).
+
+```
+garf <PATH_TO_QUERIES> --source merchant-api \
+  --output <OUTPUT_TYPE> \
+  --source.<SOURCE_PARAMETER=VALUE>
+```
+
+where:
+
+* `<PATH_TO_QUERIES>` - local or remove files containing queries
+* `<OUTPUT_TYPE>` - output supported by [`garf-io` library](../garf_io/README.md).
+* `<SOURCE_PARAMETER=VALUE` - key-value pairs to refine fetching, check [available source parameters](#available-source-parameters).
+
+## Available source parameters
+
+| name | values| comments |
+|----- | ----- | -------- |
+| `account`   | Account(s) to get data to | Multiple accounts are supported, should be comma-separated|

libs/garf_community/google/merchant/garf_merchant_api/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines simplified imports."""
+
+from __future__ import annotations
+
+from garf_merchant_api.api_clients import MerchantApiClient
+from garf_merchant_api.report_fetcher import (
+  MerchantApiReportFetcher,
+)
+
+__all__ = [
+  'MerchantApiClient',
+  'MerchantApiReportFetcher',
+]
+
+__version__ = '0.0.1'

libs/garf_community/google/merchant/garf_merchant_api/api_clients.py

@@ -0,0 +1,51 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Creates API client for Merchant API."""
+
+from google.shopping import merchant_reports_v1beta
+from typing_extensions import override
+
+from garf_core import api_clients, query_editor
+from garf_merchant_api import exceptions
+
+
+class MerchantApiError(exceptions.GarfMerchantApiError):
+  """API specific error."""
+
+
+class MerchantApiClient(api_clients.BaseClient):
+  def __init__(
+    self,
+    **kwargs: str,
+  ) -> None:
+    """Initializes MerchantClient."""
+    self.query_args = kwargs
+
+  @override
+  def get_response(
+    self, request: query_editor.BaseQueryElements, **kwargs: str
+  ) -> api_clients.GarfApiResponse:
+    if not (account := kwargs.get('account')):
+      raise MerchantApiError('Missing account parameter')
+    client = merchant_reports_v1beta.ReportServiceClient()
+    merchant_request = merchant_reports_v1beta.SearchRequest(
+      parent=f'accounts/{account}',
+      query=request.text,
+    )
+    response = client.search(request=merchant_request)
+    results = []
+    for page in response:
+      for result in page.get('results'):
+        results.append(result)
+    return api_clients.GarfApiResponse(results=results)

libs/garf_community/google/merchant/garf_merchant_api/exceptions.py

@@ -0,0 +1,19 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from garf_core import exceptions
+
+
+class GarfMerchantApiError(exceptions.GarfError):
+  """Base class for all library exceptions."""

libs/garf_community/google/merchant/garf_merchant_api/query_editor.py

@@ -0,0 +1,30 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Defines MerchantQuery."""
+
+from garf_core import query_editor
+
+
+class MerchantApiQuery(query_editor.QuerySpecification):
+  """Query to Knowledge Graph Search api."""
+
+  def __init__(
+    self,
+    text: str,
+    title: str | None = None,
+    args: dict[str, str] | None = None,
+    **kwargs,
+  ) -> None:
+    """Initializes MerchantApiQuery."""
+    super().__init__(text, title, args, **kwargs)

libs/garf_community/google/merchant/garf_merchant_api/report_fetcher.py

@@ -0,0 +1,32 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines report fetcher."""
+
+from garf_core import parsers, report_fetcher
+from garf_merchant_api import MerchantApiClient, query_editor
+
+
+class MerchantApiReportFetcher(report_fetcher.ApiReportFetcher):
+  """Defines report fetcher."""
+
+  def __init__(
+    self,
+    api_client: MerchantApiClient = MerchantApiClient(),
+    parser: parsers.BaseParser = parsers.NumericConverterDictParser,
+    query_spec: query_editor.MerchantApiQuery = query_editor.MerchantApiQuery,
+    **kwargs: str,
+  ) -> None:
+    """Initializes MerchantApiReportFetcher."""
+    super().__init__(api_client, parser, query_spec, **kwargs)

libs/garf_community/google/merchant/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "garf-merchat-api"
+dependencies = [
+  "garf-core",
+  "garf-io",
+  "google-shopping-merchant-reports",
+]
+authors = [
+  {name = "Google Inc. (gTech gPS CSE team)", email = "no-reply@google.com"},
+]
+license = {text = "Apache 2.0"}
+requires-python = ">=3.8"
+description = "Garf implementation for Google Merchant API"
+readme = "README.md"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python"
+]
+
+dynamic=["version"]
+
+[tool.setuptools.dynamic]
+version = {attr = "garf_merchant_api.__version__"}
+
+[project.entry-points.garf]
+merchant-api = "garf_merchant_api.report_fetcher"
+
+[options.extras_require]
+test =  [
+  "pytest",
+  "pytest-cov",
+  "python-dotenv",
+]
+
+[project.scripts]