{"id":13879728,"url":"https://github.com/filestack/filestack-ruby","last_synced_at":"2025-04-07T11:09:46.900Z","repository":{"id":48439900,"uuid":"89370566","full_name":"filestack/filestack-ruby","owner":"filestack","description":"Official Ruby SDK for Filestack - API and content management system that makes it easy to add powerful file uploading and transformation capabilities to any web or mobile application. ","archived":false,"fork":false,"pushed_at":"2023-12-18T18:06:44.000Z","size":5620,"stargazers_count":34,"open_issues_count":3,"forks_count":27,"subscribers_count":12,"default_branch":"develop","last_synced_at":"2024-04-26T19:49:15.058Z","etag":null,"topics":["hacktoberfest","ruby","sdk-ruby","transforming-files","upload-file","upload-images"],"latest_commit_sha":null,"homepage":"https://www.filestack.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filestack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-04-25T14:31:46.000Z","updated_at":"2024-04-26T19:49:15.059Z","dependencies_parsed_at":"2023-12-18T22:28:57.130Z","dependency_job_id":"78e3d4ec-0079-4622-ab98-d240da1cb69c","html_url":"https://github.com/filestack/filestack-ruby","commit_stats":{"total_commits":163,"total_committers":11,"mean_commits":"14.818181818181818","dds":"0.45398773006134974","last_synced_commit":"5893aebc48181e217699f592ffc5c7af26332667"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filestack","download_url":"https://codeload.github.com/filestack/filestack-ruby/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640465,"owners_count":20971557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","ruby","sdk-ruby","transforming-files","upload-file","upload-images"],"created_at":"2024-08-06T08:02:30.525Z","updated_at":"2025-04-07T11:09:46.878Z","avatar_url":"https://github.com/filestack.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"logo.svg\" align=\"center\" width=\"100\"/\u003e\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eFilestack Ruby SDK\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/filestack/filestack-ruby.svg?branch=master\"\u003e\n    \u003cimg src=\"https://img.shields.io/travis/filestack/filestack-ruby/master.svg?longCache=true\u0026style=flat-square\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/filestack/filestack-ruby?branch=master\"\u003e\n    \u003cimg src=\"https://img.shields.io/coveralls/github/filestack/filestack-ruby/master.svg?longCache=true\u0026style=flat-square\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\nRuby SDK for Filestack API and content management system.\n\u003c/p\u003e\n\n**Important: This is the readme for 2.1.0.**\nA recent change (2.1.0) has renamed the `Client` to `FilestackClient`, and the `Filelink` to `FilestackFilelink`. Please make neccessary changes before upgrading to newest release if you run 2.0.1 or 2.0.0. This was to address namespace concerns by users with models and attributes named `Client`, and to be more consistent.\n\n## Overview\n\n* A multi-part uploader powered on the backend by the [Filestack CIN](https://www.filestack.com/products/content-ingestion-network).\n* An interface to the [Filestack Processing Engine](https://www.filestack.com/docs/image-transformations) for transforming assets via URLs.\n* The Filestack Picker - an upload widget for the web that integrates over a dozen cloud providers and provides pre-upload image editing.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'filestack'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install filestack\n\n## Usage\n\n### Import\n```ruby\nrequire 'filestack'\n```\nIntialize the client using your API key, and security if you are using it.\n\n```ruby\nclient = FilestackClient.new('YOUR_API_KEY', security: security_object)\n```\n### Uploading\n```ruby\nfilelink = client.upload(filepath: '/path/to/localfile')\n\n# OR\n\nfilelink = client.upload(external_url: 'http://domain.com/image.png')\n\n\n# Return response body on upload complete\nputs filelink.upload_response\n\n# Return uploaded filelink handle\nputs filelink.handle\n```\n\nTo upload a local, an IO object and an external file with following optional options:\n\n```ruby\noptions = {\n  filename: 'string',\n  location: 'string',\n  path: 'string',\n  container: 'string',\n  mimetype: 'string',\n  region: 'string',\n  workflows: ['workflow-id-1', 'workflow-id-2'],\n  upload_tags: {\n    key: 'value',\n    key2: 'value'\n  }\n}\n\nfilelink = client.upload(filepath: '/path/to/localfile', options: { mimetype: 'image/png', filename: 'custom_filename.png' })\n\nfilelink = client.upload(external_url: 'http://domain.com/image.png', options: { mimetype: 'image/jpeg', filename: 'custom_filename.png' })\n```\n\nTo store file on `dropbox`, `azure`, `gcs` or `rackspace`, you must have the chosen provider configured in the developer portal to enable this feature. By default the file is stored on `s3`. You can add more details of the storage in `options`.\n\n```ruby\nfilelink = client.upload(filepath: '/path/to/file', storage: 's3', options: { path: 'folder_name/', container: 'container_name', location: 's3', region: 'region_name' })\n\nfilelink = client.upload(external_url: 'http://someurl.com/image.png', options: { location: 'dropbox', path: 'folder_name' })\n```\n\n### Workflows\nWorkflows allow you to wire up conditional logic and image processing to enforce business processes, automate ingest, and save valuable development time. In order to trigger the workflow job for each upload:\n\n```ruby\nfilelink = client.upload(filepath: '/path/to/file', options: { workflows: [\"workflow_id_1\", \"workflow_id_2\"] })\n\n#OR\n\nfilelink = client.upload(external_url: 'http://someurl.com/image.png', options: { workflows: [\"workflow_id_1\"] })\n\n# Return workflows jobids on upload complete\nputs filelink.upload_response[\"workflows\"]\n```\n\n### Security\nIf security is enabled on your account, or if you are using certain actions that require security (delete, overwrite and certain transformations), you will need to create a security object and pass it into the client on instantiation.\n\n```ruby\nsecurity = FilestackSecurity.new('YOUR_APP_SECRET', options: {call: %w[read store pick runWorkflow]})\nclient = FilestackClient.new('YOUR_API_KEY', security: security)\n```\n\n### Using FilestackFilelinks\nFilestackFilelink objects are representation of a file handle. You can download, get raw file content, delete and overwrite file handles directly. Security is required for overwrite and delete methods.\n\nInitialize the filelink using the file handle, your API key, and security if required. The file handle is the string following the last slash `/` in the file URL.\n\n```ruby\nfilelink = FilestackFilelink.new(handle, apikey: 'YOUR_API_KEY', security: security_object)\n```\n\n### Deletion\nYou can delete a file by simply calling `delete` on the filelink.\n\n```ruby\nfilelink.delete\n```\n\n### Transformations\nTransforms can be initiated one of two ways. The first, by calling ```transform``` on a filelink:\n\n```ruby\ntransform = filelink.transform\n```\n\nOr by using an external URL via the client:\n\n```ruby\ntransform = client.transform_external('https://someurl.com')\n```\n\nTransformations can be chained together as you please.\n\n```ruby\ntransform = filelink.transform.resize(width: 100, height: 100).flip.enhance\n```\n\nYou can retrieve the URL of a transform object:\n\n```ruby\ntransform.url\n```\n\nOr you can store (upload) the transformation as a new filelink:\n\n```ruby\nnew_filelink = transform.store\n```\n\nFor a list of valid transformations, please see [here](https://www.filestack.com/docs/image-transformations).\n\n### Fallback\nReturn `default` file if the source of the transformation does not work or the transformation fails.\nTo use fallback, you should provide `handle` of the file that should be returned. Optionally, you can add `cache`, which means number of seconds fallback response should be cached in CDN.\n\n```ruby\ntransform = client.transform_external('https://someurl.com/file.png').fallback(file: 'DEFAULT_HANDLE_OR_FILEPATH')\n```\n\nIf you are using fallback handle that belongs to different application than the one which runs transformation (APIKEY) and it is secured with security policy, appropriate signature and policy with read call should be used:\n\n```ruby\ntransform = client.transform_external('https://someurl.com/file.png').fallback(file: 'DEFAULT_HANDLE_OR_FILEPATH?policy=HANDLE_APIKEY_POLICY\u0026signature=HANDLE_APIKEY_SIGNATURE', cache: 10)\n```\n\n### Content\nSets `Content-Disposition` header for given file.\n\n```ruby\ntransform = filelink.transform.content(filename: 'DEFAULT_FILENAME', type: 'TYPE')\n```\n\n### Tagging\n\nIf you have auto-tagging enabled onto your account, it can be called on any filelink object (tags don't work on external URLs).\n\n```ruby\ntags = filelink.tags\n```\n\nThis will return a hash with labels and their associated confidence:\n\n```ruby\n{\n    \"auto\" =\u003e {\n        \"art\"=\u003e73,\n        \"big cats\"=\u003e79,\n        \"carnivoran\"=\u003e80,\n        \"cartoon\"=\u003e93,\n        \"cat like mammal\"=\u003e92,\n        \"fauna\"=\u003e86, \"mammal\"=\u003e92,\n        \"small to medium sized cats\"=\u003e89,\n        \"tiger\"=\u003e92,\n        \"vertebrate\"=\u003e90},\n    \"user\" =\u003e nil\n}\n```\n\nSFW is called the same way, but returns a boolean value (true == safe-for-work, false == not-safe-for-work).\n\n```ruby\nsfw = filelink.sfw\n```\n\n## Versioning\n\nFilestack Ruby SDK follows the [Semantic Versioning](http://semver.org/).\n\n## Issues\n\nIf you have problems, please create a [Github Issue](https://github.com/filestack/filestack-ruby/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilestack%2Ffilestack-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilestack%2Ffilestack-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilestack%2Ffilestack-ruby/lists"}