Merge histories

.github/workflows/gitleaks.yml

@@ -0,0 +1,13 @@
+name: Gitleaks
+
+on: [push,pull_request]
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: gitleaks-action
+      uses: Nitro/gitleaks-action@master
+      # This uses our fork of the action
+

.gitignore

@@ -0,0 +1,18 @@
+# Environment variables
+.env
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# OS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo

README.md

@@ -1,2 +1,72 @@
-# nitro-platform-integrations
-Examples and tools for integrating with Nitro Platform API (document conversion, extraction, transformation)
+# Nitro Platform API Integrations
+
+This repository provides examples and tools for integrating with the Nitro Platform API, enabling document conversion, extraction, transformation, and workflow automation.
+
+## What is the Platform API?
+
+The Nitro Platform API provides programmatic access to document processing capabilities including:
+- **Document Conversions**: Convert between formats (Word↔PDF, Excel→PDF, PowerPoint→PDF, etc.)
+- **Data Extraction**: Extract text, form data, tables, and detect PII from documents
+- **Document Transformations**: Compress, merge, split, redact, password protect, and more
+- **Async Processing**: Handle large documents with job-based workflows
+
+## Repository Structure
+
+```
+├── postman/                    # Postman collection and environment
+├── power-automate/            # Custom connector and sample flows
+├── samples/
+│   └── python/               # Python examples
+└── docs/                     # API documentation and guides
+```
+
+## Getting Started
+
+### Prerequisites
+
+1. **API Access**: Get OAuth2 client credentials:
+   - Go to [https://admin.gonitro.com](https://admin.gonitro.com)
+   - Navigate to **Settings** → **API**
+   - Click **Create Application**
+   - Name your application and save the Client ID and Client Secret
+
+2. **Environment Setup**: Set the following variables:
+   ```bash
+   export PLATFORM_BASE_URL=https://api.gonitro.dev
+   export PLATFORM_CLIENT_ID=<YOUR_CLIENT_ID>
+   export PLATFORM_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
+   ```
+
+### Quick Start Options
+
+#### Using Postman
+1. Import the collection from `postman/Platform-API.postman_collection.json`
+2. Configure environment variables (see `postman/README.md`)
+3. Get a bearer token and run sample requests
+
+#### Using Power Automate
+1. Create a custom connector using instructions in `power-automate/`
+2. Configure API key authentication
+3. Build flows for document processing workflows
+
+#### Using Sample Code
+- **Python**: See `samples/python/README.md`
+
+## Authentication
+
+The API uses OAuth2 authentication:
+1. Exchange client credentials for an access token via `POST /oauth/token`
+2. Include the token in requests: `Authorization: Bearer <ACCESS_TOKEN>`
+
+See the [authentication documentation](https://developers.gonitro.com/docs/api-reference/authentication/get-access-token) for details.
+
+## Common Workflows
+
+- **Document Conversion**: Upload a file → Get converted result
+- **Async Processing**: Start job → Poll status → Download result
+- **Data Extraction**: Upload PDF → Extract text/tables/forms
+- **Document Transformation**: Upload PDF → Apply operations → Download result
+
+## Support
+
+For API documentation and support, visit the [developer portal](https://developers.gonitro.dev).

docs/API-overview.md

@@ -0,0 +1,74 @@
+# API Overview
+
+The Nitro Platform API provides document processing capabilities through a RESTful interface.
+
+## Base URL
+
+All API requests are made to: `https://api.gonitro.dev`
+
+## Authentication
+
+The API uses OAuth2 client credentials flow:
+
+1. **Get Credentials**: Create an application at [admin.gonitro.com](https://admin.gonitro.com) → Settings → API
+2. **Get Token**: Exchange credentials for access token via `POST /oauth/token`
+3. **Use Token**: Include in requests as `Authorization: Bearer <ACCESS_TOKEN>`
+
+## Request/Response Patterns
+
+### Synchronous Operations
+- Submit request with file
+- Get immediate response with result
+- Best for: Small files, simple operations
+
+### Asynchronous Operations
+- Submit request, get job ID
+- Poll `/jobs/{jobId}/status` for progress
+- Download result when complete
+- Best for: Large files, complex operations
+
+## API Categories
+
+### Conversions (`/platform/conversions`)
+Convert documents between formats:
+- Word ↔ PDF
+- Excel → PDF  
+- PowerPoint → PDF
+- Images → PDF
+
+### Extractions (`/platform/extractions`)
+Extract data from documents:
+- Text extraction
+- Form data extraction
+- Table data extraction
+- PII detection
+
+### Transformations (`/platform/transformations`)
+Modify PDF documents:
+- Compress, merge, split
+- Redact content
+- Password protect/remove
+- Rotate/delete pages
+
+### Jobs (`/jobs`)
+Manage asynchronous operations:
+- Check job status
+- Download job results
+- Handle job errors
+
+## Error Handling
+
+The API returns standard HTTP status codes:
+- `200` - Success
+- `400` - Bad Request (invalid parameters)
+- `401` - Unauthorized (invalid/missing token)
+- `404` - Not Found (invalid endpoint/job ID)
+- `500` - Internal Server Error
+
+Error responses include details:
+```json
+{
+  "error": "Invalid file format",
+  "message": "Only PDF files are supported for this operation"
+}
+```

docs/workflow-examples.md

@@ -0,0 +1,104 @@
+# Workflow Examples
+
+Common end-to-end workflows using the Platform API.
+
+## Document Conversion Workflow
+
+**Goal**: Convert Word documents to PDF
+
+### Using Postman
+1. Run "Get Bearer Token" request
+2. Use "Word → PDF" request with your .docx file
+3. Download the converted PDF from response
+
+### Using Python
+```python
+token = get_access_token(client_id, client_secret)
+with open('document.docx', 'rb') as f:
+    result = convert_to_pdf(token, f)
+with open('document.pdf', 'wb') as f:
+    f.write(result)
+```
+
+### Using Power Automate
+1. **Trigger**: When file added to SharePoint
+2. **Action**: Convert using custom connector
+3. **Action**: Save result back to SharePoint
+
+## Data Extraction Workflow
+
+**Goal**: Extract text and tables from PDF invoices
+
+### Steps
+1. **Upload PDF**: Submit to `/platform/extractions/pdf-text`
+2. **Extract Tables**: Submit to `/platform/extractions/pdf-table-data`
+3. **Process Data**: Parse extracted JSON for relevant fields
+4. **Store Results**: Save to database/spreadsheet
+
+### Use Cases
+- Invoice processing
+- Form data extraction
+- Document analysis
+- Content migration
+
+## Async Processing Workflow
+
+**Goal**: Process large documents without timeouts
+
+### Steps
+1. **Submit Job**: POST to conversion/extraction endpoint
+2. **Get Job ID**: Note the `jobId` from response
+3. **Poll Status**: GET `/jobs/{jobId}/status` until `status: "completed"`
+4. **Download Result**: GET `/jobs/{jobId}/result`
+
+### Implementation Pattern
+```python
+# Submit job
+job_response = submit_conversion_job(token, file_data)
+job_id = job_response['jobId']
+
+# Poll until complete
+while True:
+    status = get_job_status(token, job_id)
+    if status['status'] == 'completed':
+        break
+    elif status['status'] == 'failed':
+        raise Exception(f"Job failed: {status['message']}")
+    time.sleep(5)  # Wait 5 seconds before next check
+
+# Download result
+result = get_job_result(token, job_id)
+```
+
+## Batch Processing Workflow
+
+**Goal**: Process multiple documents efficiently
+
+### Strategy
+1. **Queue Jobs**: Submit all files as async jobs
+2. **Track Progress**: Monitor all job IDs
+3. **Download Results**: Collect completed results
+4. **Handle Errors**: Retry failed jobs
+
+### Best Practices
+- Use async processing for files > 10MB
+- Add delays between API calls (rate limiting)
+- Implement retry logic for failed requests
+- Log all operations for debugging
+
+## Document Pipeline Workflow
+
+**Goal**: Complete document processing pipeline
+
+### Example: Invoice Processing
+1. **Convert**: Word/Excel invoices → PDF
+2. **Extract**: Text and table data from PDFs
+3. **Validate**: Check extracted data quality
+4. **Transform**: Redact sensitive information
+5. **Store**: Save processed documents and data
+
+### Integration Points
+- **Input**: SharePoint, OneDrive, email attachments
+- **Processing**: Platform API operations
+- **Output**: Database, CRM, accounting system
+- **Notifications**: Email, Teams, Slack alerts